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1. INTRODUCTION 


CP/M is a monitor control program for microcomputer system 
development which uses IBM-compatible flexible disks for t ba £^P 
storage. Using a computer mainframe based upon Intel s 8080 
microcomputer, CP/M provides a general environment for program 

construction, storage, and editing, along with assembly and 

program check-out facilities. An important feature of CP/M is 
that it can be easily altered to execute with any computer 

configuration which uses an Intel 8080 (or (Ziloq Z—80) Central 
Processing Unit, and has at least 16K bytes of main memory with 
up to four IBM-compatible diskette drives. A detailed 

discussion of the modifications required for any particular 
hardware environment is given in the Exidy Inc. document 
entitled "CP/M System Alteration Guide". Although the standard 
Exidy version operates on a single-density Intel MDS 800, 
several different hardware manufacturers support their own 
input-output drivers for CP/M. - 

The CP/M monitor provides rapid access to programs through 
a comprehensive file management package. The file subsystem 
supports a named file structure, allowing dynamic allocation of 
file space as well as sequential and random file access. Using 
this file system, a large number of distinct programs can be 
stored in both source and machine executable form. 

CP/M also supports a powerful context editor. 

CP/M is logically divided into several distinct parts: 

BIOS Basic I/O System (hardware dependent) 

BDOS Basic Disk Operating System 

CCP Console Command Processor 

TPA Transient Program Area 

The BIOS provides the primitive operations necessary to 
access the diskette drives and to interface standard 
peripherals (TTY, CRT, paper tape reader/punch, and user- 
defined peripherals), and can be tailored by the user to any 
particular hardware environment by "patching" this portion o 
CP/M. The BDOS provides disk management by controlling one or 
more disk drives containing independent file directories. The 
BDOS implements disk allocation strategies ” u ’ 
dynamic file construction while minimizing 
the disk during access. Any particular 
number of records, not exceeding the size 
In a standard CP/M system, each disk can 
distinct files. The 


which provide fully 
head movement across 
file may contain any 
of any single disk, 
contain up to 64 
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BDOS has entry points which include the following primitive operations which 
can be programmatically accessed: 

took for a particular disk file by name. 

Open a file for further operations. 

Close a file after processing. 

Change the name of a particular file. 

Read a record from a particular file. 

Write a record onto the disk. 

Select a particular disk drive for further 
operations. 

The CCP provides symbolic interface between the users console and the 
remainder of the CP/M system. The CCP reads the console device and processes 
commands which include listinq the file directory, printinq the contents of 
files, and controlling the operation of transient programs, such as 
assemblers, editors, and debuggers. The standard commands which are available 
in the CCP are listed in a following section. 

* ast segment of CP/M is the area called the Transient Program Area 
(TPA). The TPA holds programs which are loaded from the disk tnder command of 
the CCP. Durinq program editing, for example, the TPA holds the CP/M text 
editor machine code and data areas. Similarly, programs created inder CP/M 
can be checked out by loading and executing these programs in the TPA. 


SEARCH 

OPEN 

CLOSE 

RENAME 

READ 



It should be mentioned that any or all of the CP/M component subsystems 
can be overlayed" by an executinq program. That is, once a user's program is 
loaded into the TPA, the CCP, BDOS, and BIOS areas can be used as the 
P^ ram s area. A "bootstrap" loader is programmatically accessible 

whenever the BIOS portion is not overlayed; thus, the user program need only 
branch to the bootstrap loader at the end of execution, and the complete CP/M 
monitor is reloaded from disk. 


It should be reiterated that the CP/M operating system is partitioned 
into distinct modules, including the BIOS portion which defines the hardware 
environment in which CP/M is executing. Thus, the standard system can be 
easily modified to any non-standard environment by changing the peripheral 
drivers to handle the custom system. 
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2. FUNCTIONAL DESCRIPTION OF CP/M. 


The user interacts with CP/M primarily through the CCP, which reads and 
interprets commands entered through the console. In general, the CCP 
addresses one of several disks which are online (the standard system addresses 
up to four different disk drives). These disk drives are labelled A, B, C, 
and D. A disk is "logged in" if the CCP is currently addressing the disk. In 
order to clearly indicate vdnich disk is the currently logged disk, the CCP 
always prompts the operator with the disk name followed by the symbol 
indicating that the CCP is ready for another command. Upon initial start up, 
the CP/M system is brought in from disk A, and the CCP displays the message 

xxK CP/M VER m.m 

where xx is the memory size (in kilobytes) which this CP/M system manages, and 
m.m is the CP/M version number. All CP/M systems are initially set to operate 
in a 16K memory space, but can be easily reconfigured to fit any memory size 
on the host system (see the MDVCPM transient command). Fallowing system 
signon, CP/M automatically logs in disk A, prompts the user with the symbol 
"A>" (indicating that CP/M is currently addressing disk "A") , and waits for a 
command. The commands are implemented at two levels: built-in commands and 
transient commands. 

2.1. GENERAL COMMAND STRUCTURE. 

Built-in commands are a part of the CCP program itself, vtfiile transient 
commands are loaded into the TPA from disk and executed. The built-in 
commands are 

ERA Erase specified files. 

DIR List file names in the directory. 

REN Rename the specified file. 

SAVE Save memory contents in a file. 

TYPE Type the contents of a file on the logged disk. 

Nearly all of the commands reference a particular file or group of files. The 
form of a file reference is specified below. 


2.2. FILE REFERENCES. 

A file reference identifies a particular file or group of files on a 
particular disk attached to CP/M. These file references can be either 
“unambiguous" (ufn) or "ambiguous" (afn). An unambiguous file reference 
uniquely identifies a single file, while an ambiguous file reference may be 
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satisfied by a number of different files. 

File references consist of two parts: the primary name and the secondary 
name. Although the secondary name is optional, it usually is generic; that 
is, the secondary name "ASM," for example, is used to denote that the file is 
an assembly language source file, while the primary name distinguishes each 
particular source file. The two names are separated by a "." as shown below: 

pppppppp.sss 

where pppppppp represents the primary name of eight characters or less, and 
sss is the secondary name of no more than three characters. As mentioned 
above, the name 

pppppppp 

is also allowed and is equivalent to a secondary name consisting of three 
blanks. The characters used in specifying an unambiguous file reference 
cannot contain any of the special characters 

<>•»*:* ? * [ ] 

while all alphanumerics and remaining special characters are allowed. 

An ambiguous file reference is used for directory search and pattern 
matching. The form of an ambiguous file reference is similar to an 
unambiguous reference, except the symbol "?" may be interspersed throughout 
the primary and secondary names. In various commands throughout CP/M, the "?" 
symbol matches any character of a file name in the "?" position. Thus, the 
ambiguous reference 


X?Z.C?M 

is satisfied by the unambiguous file names 


XYZ.ODM 

and 

X3Z.CAM 

Note that the ambiguous reference 


* * 

is equivalent to the ambiguous file reference 
????????.??? 


while 
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and 


pppppppp.* 

*.sss 

are abbreviations for 


and 


PFPPPPPP.??? 
????????.sss 


respectively. As an example, 
DIR *.* 


is interpreted by the CCP as a command to list the names of all disk files in 
the directory, while 

DIR X.Y 

searches only for a file by the name X.Y Similarly, the command 
DIR X?Y.C?M 

causes a search for all (unambiguous) file nanes on the disk vhich satisfy 
this ambiguous reference. 

The following file names are valid unambiguous file references: 

X XYZ GAMMA 

X.Y XYZ.ODM GAMMA.1 


As an added convenience, the programmer can generally specify the disk 
drive nane along with the file name. In this case, the drive name is given as 
a letter A through Z followed by a colon (:). The specified drive is then 
"logged in" before the file operation occurs. Thus, the following are valid 
file names with disk name prefixes: 

A:X.Y B:XYZ C:GAMMA 

Z:XYZ.CDM B:X.A?M C:*.ASM 

It should also be noted that all alphabetic lower case letters in file 
and drive names are always translated to upper case vtfien they are processed by 
the CCP. 
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3. SWITCHING DISKS. 

The operator can switch the currently logged disk by typing the disk 
drive name (A, B, C, or D) followed by a colon (:) when the CCP is waiting for 
console input. Thus, the sequence of prompts and commands shown below might 
occur after the CP/M system is loaded from disk As 


16K CP/M VER 1.4 


A>DIR 


List all files on disk A. 


SAMPLE ASM 


SAMPLE PRN 


A>B: 


Switch to disk B 


B>DIR *.ASM 


List all ••ASM" files on B 


DUMP ASM 


FILES ASM 


B>A: 


Switch back to A, 


6 








4. THE FORM CF BUILT-IN COMMANDS. 

The file and device reference forms described above can now be used to 
fully specify the structure of the built-in ccmmands. In the description 
below, assume the following abbreviations: 


ufn 

- 

unambiguous file reference 

afn 

- 

ambiguous file reference 

cr 

— 

carriage return 


Further, recall that the CCP always translates lower case characters to upper 
case characters internally. Thus, lower case alphabetics are treated as if 
they are upper case in command names and file references. 


4.1 ERA afn cr 

The ERA (erase) command removes files from the currently loqged-in disk 
(i.e., the disk name currently prompted by CP/M preceding the ">"). The files 
which are erased are those which satisfy the ambiguous file reference afn. 
The following examples illustrate the use of ERA: 

ERA X.Y The file named X.Y on the currently logged disk 

is renoved from the disk directory, and the space 
is returned. 

ERA X.* All files with primary name X are removed from 

the current disk. 


ERA *.ASM 


All files with secondary name ASM are removed 
frcm the current disk. 


ERA X?Y.C?M 

ERA *.* 


ERA B:*.FRN 


All files on the current disk which satisfy the 
ambiguous reference X?Y.C?M are deleted. 

Erase all files on the current disk (in this case 
the CCP prompts the console with the message 
"ALL FII£S (Y/N)?" 

which requires a Y response before files are 
actually removed). 

All files on drive B which satisfy the ambiguous 
reference ????????.PRN are deleted, independently 
of the currently logged disk. 
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4.2. DIR afn cr 


The DIR (directory) command causes the names of all files which satisfy 
the ambiguous file name afn to be listed at the console device. As a special 
case, the canmand 

DIR 

lists the files on the currently logged disk (the canmand "DIR M is equivalent 
to the canmand "DIR *.*"). Valid DIR commands are shown below. 

DIR X.Y 

DIR X?Z.C?M 

DIR ??.Y 

Similar to other CCP commands, the afn can be preceded by a drive name. 
The following DIR commands cause the selected drive to be addressed before the 
directory search takes place. 

DIR B: 

DIR B:X.Y 

DIR B:*.A?M 

If no files can be found on the selected diskette which satisfy the 
directory request, then the message “NOT FOUND" is typed at the console. 


4.3. REN ufnl=ufn2 cr 

The REN (rename) command allows the user to change the names of files on 
disk. The file satisfying ufn2 is changed to ufnl. The currently logged disk 

is assumed to contain the file to rename (ufnl). The CCP also allows the user 

to type a left-directed arrow instead of the equal sign, if the user's console 
supports this graphic character. Examples of the REN canmand are 

REN X.Y=Q.R The file Q.R is changed to X.Y. 

REN XYZ.CDM=XYZ.XXX 0116 file XYZ.XXX is changed to XYZ.COM. 

The cperator can precede either ufril or ufn2 (or both) by an optional 
drive address. Given that ufril is preceded by a drive name, then ufn2 is 
assumed to exist on the same drive as ufhl. Similarly, if ufh2 is preceded by 
a drive name, then ufril is assumed to reside on that drive as well. If both 
ufnl and ufn2 are preceded by drive names, then the same drive must be 
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specified in both cases. The following REN commands illustrate this format. 

REN AsX.ASM = Y.ASM The file Y.ASM is changed to X.ASM on 

drive A. 

REN B:ZAP.BAS=ZOT.BAS The file ZOT.BAS is changed to ZAP.BAS 

on drive B. 

REN BrA.ASM = BrA.BAK The file A.BAR is renamed to A.ASM on 

drive B. 

If the file ufnl is already present, the REN command will respond with 
the error "FILE EXISTS" and not perform the change. If ufn2 does not exist on 
the specified diskette, then the message "NOT POUND" is printed at the 
console. 


4.4. SAVE n ufn cr 

The SAVE command places n pages (256-byte blocks) onto disk from the TPA 
and names this file ufn. In the CP/M distribution system, the TPA starts at 
100H (hexadecimal), which is the second paqe of memory. Thus, if the user's 
program occupies the area from 100H through 2FFH, the SAVE command must 
specify 2 pages of memory. The machine code file can be subsequently loaded 
and executed. Examples are: 


SAVE 

3 X.OOM 

Gopies 100H through 3FFH to X.OOM. 

SAVE 

40 0 

Copies 100H through 28FFH to Q (note 
that 28 is the page count in 28FFH, 
and that 28H = 2*16+8 = 40 decimal). 

SAVE 

4 X.Y 

Copies 100H through 4FFH to X.Y. 


The SAVE command can also specify a disk drive in the afn portion of the 
command, as shown below. 

SAVE 10 B:ZOT.OOM Copies 10 pages (100H through 0AFFH) to 

the file ZOT.OOM on drive B, 


4.5. TYPE ufn cr 

The TYPE command displays the contents of the ASCII source file ufn on 
the currently logged disk at the console device. Valid TYPE commands are 

TYPE X.Y 
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TYPE X.PLM 


TYPE XXX 

The TYPE command expands tabs (clt-I characters), assuming tab positions 
are set at e/ery eighth colurm. The ufn can also reference a drive name as 
shown below. 

TYPE B:X.PKN The file X.PRN from drive B is displayed. 
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5. LINE EDITING AND OUTPUT CONTROL. 

The CCP allows certain line editing functions while typing command lines. 



rubout 

Delete and echo the last character typed at the 
console. 


ctl-U 

Delete the entire line typed at the console. 


Ctl-X 

(Same as ctl-U) 

¥ 

ctl-R 

Retype current command line: types a "clean line" fol¬ 
lowing character deletion with rubouts. 


Ctl-E 

Physical end of line: carriage is returned, but line 
is not sent until the carriage return key is depressed. 


ctl-C 

CP/M system reboot (warm start) 


ctl-Z 

End input from the console (used in PIP and ED). 


The control functions ctl-P and ctl-S affect console output as shown below. 


Copy all subsequent console output to the currently 
assigned list device (see the STAT command). Output 
is sent to both the list device and the console device 
until the next ctl-P is typed. 

Stop the console output temporarily. Program execution 
and output continue when the next character is typed 
at the console (e.q., another ctl-S). This feature is 
used to stop output on high speed consoles, such as 
CRT's, in order to view a segment of output before con¬ 
tinuing. 

Note that the ctl-key sequences shown above are obtained by depressing the 
control and letter keys simultaneously. Further, CCP command lines can 
generally be up to 255 characters in length; they are not acted upon intil the 
carriage return key is typed. 


ctl-P 



ctl-S 
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6. TRANSIENT (DMMAND6. 


Transient commands are loaded from the currently logged disk and executed 
in the TPA. The transient commands defined for execution under the CCP are 
shown below. Additional functions can easily be defined by the user (see the 
LOAD command definition). 


STAT 

List the number of bytes of storage remaining on the 
currently logged disk, provide statistical information 
about particular files, and display or alter device 
assignment. 

ASM 

load the CP/M assembler and assemble the specified 
program from disk. 

LOAD 

load the file in Intel "hex" machine code format and 
produce a file in machine executable form which can be 
loaded into the TPA (this loaded program becomes a 
new command under the CCP). 

DDT 

Load the CP/M debugger into TPA and start execution. 

PIP 

Load the Peripheral Interchange Program for subsequent 
disk file and peripheral transfer operations. 

ED 

Load and execute the CP/M text editor program. 

SYSGEN 

Create a new CP/M system diskette. 

SUBMIT 

Submit a file of commands for batch processing. 

DUMP 

Dump the contents of a file in hex. 

MOVCPM 

Regenerate the CP/M system for a particular memory 
size. 


Transient commands are specified in the same manner as built-in commands, and 
additional commands can be easily defined by the user. As an added 
convenience, the transient command can be preceded by a drive nane, which 
causes the transient to be loaded from the specified drive into the TPA for 
execution. Thus, the command 

B:STAT 

causes CP/M to temporarily "log in" drive B for the source of the STAT 
transient, and then return to the original logged disk for subseguent 
processing. 
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The basic transient commands are listed in detail below. 

6.1. STAT cr 

Hie STAT command provides general statistical information about file 
storage and device assignment. It is initiated by typing one of the following 
forms: 

STAT cr 

STAT "command line" cr 

Special forms of the "command line" allow the current device assignment to be 
examined and altered as well. The various command lines vhich can be 
specified are shown below, with an explanation of each form shown to the 
right. 

STAT cr If the user types an empty command line, the STAT 

transient calculates the storage remaining on all 
active drives, and prints a message 

x: R/W, SPACE: nnnK 
or 

x: R/O, SPACE: nnnK 

for each active drive x, vrfiere R/W indicates the 
drive may be read or written, and R/0 indicates 
the drive is read only (a drive becomes R/O by 
explicitly setting it to read only, as shown 
below, or by inadvertantly changing diskettes 
without performing a warm start). The space 
remaining on the diskette in drive x is given 
in kilobytes by nnn. 

STAT x: cr If a drive name is given, then the drive is 

selected before the storage is computed. Thus, 
the command "STAT B:" could be issued while 
logged into drive A, resulting in the message 

BYTES REMAINING ON B: nnnK 

STAT afn cr The command line can also specify a set of files 

to be scanned by STAT. The files vhich satisfy 
afri are listed in alphabetical order, with stor¬ 
age requirements for each file under the heading 

RECS BYTS EX D: FILENAME.TYP 

rrrr bbbK ee d:pppppppp.sss 

where rrrr is the number of 128-byte records 
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allocated to the file, bbb is the number of kilo¬ 
bytes allocated to the file (bbb=rrrr*128/1024), 
ee is the number of 16K extensions (ee=bbb/16), 
d is the drive name containing the file (A...Z), 
PFPPPPPP is the (up to) eight-character primary 
file name, and sss is the (up to) three-character 
secondary name. After listing the individual 
files, the storage usage is summarized. 

STAT x:afn cr As a convenience, the drive name can be given 

ahead of the afn. In this case, the specified 
drive is first selected, and the form "STAT afn" 
is executed. 


STAT x:=R/0 cr This form sets the drive given by x to read-only, 

which remains in effect until the next warm or 
cold start takes place. When a disk is read-only, 
the message 

BDOS ERR ON x: READ ONLY 

will appear if there is an attempt to write to 
the read-only disk x. CP/M waits until a key 
is depressed before performing an automatic warm 
start (at which time the disk becomes R/W). 


The STAT command also allows control over the physical to logical device 
assignment (see the IOBYTE function described in the manuals “CP/M Interface 
Guide" and “CP/M System Alteration Guide"). In general, there are four 
logical peripheral devices which are, at any particular instant, each assigned 
to one of several physical peripheral devices. The four logical devices are 
named: 


CON: 

The system console device (used by CCP 
for communication with the operator) 

RDR: 

The paper tape reader device 

PUN: 

The paper tape punch device 

LST: 

The output list device 


The actual devices attached to any particular computer system are driven 
by subroutines in the BIOS portion of CP/M. Thus, the logical RDR: device, 
for example, could actually be a high speed reader. Teletype reader, or 
cassette tape. In order to allow some flexibility in device naming and 
assignment, several physical devices are defined, as shown below: 
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TTY: 

Teletype device (slow speed console) 

CRT: 

Cathode ray tube device (high speed console) 

BAT: 

Batch processing (console is current RDR:, 
output qoes to current LST: device) 

UC1: 

User-defined console 

PTR: 

Paper tape reader (high speed reader) 

UR1: 

User-defined reader #1 

UR2: 

User-defined reader #2 

PTP: 

Paper tape punch (hiqh speed punch) 

UP1: 

User-defined punch #1 

UP2: 

User-defined punch #2 

LPT: 

Line printer 

UL1: 

User-defined list device #1 


It must be emphasized that the physical device names may or may not 
actually correspond to devices which the names imply. That is, the PTP: 
device may be implemented as a cassette write operation, if the user wishes. 
The exact correspondence and driving subroutine is defined in the BIOS portion 
of CP/M. In the standard distribution version of CP/M, these devices 
correspond to their names on the MD6 800 development system. 


The possible logical to physical device assignments can be displayed by 
typing 

STAT VAL: cr 

The STAT prints the possible values vrtiich can be taken on for each logical 
device: 


CON. 

= TTY: 

CRT: 

BAT: 

UC1: 

RDR: 

= TTY: 

PTR: 

UR1: 

UR2: 

PUN: 

= TTY: 

PTP: 

UP1: 

UP2: 

LST: 

= TTY: 

CRT: 

LPT: 

UL1: 


In each case, the logical device shown to the left can take any of the four 
physical assignments shown to the right on each line. The current loqical to 
physical mapping is displayed by typinq the command 

STAT DEV: cr 
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which produces a listing of each logical device to the left, and the current 
corresponding physical device to the right. Por example, the list might 
appear as follows: 

CDN: = CRT: 

RDR: « UR1: 

PUN: = FTP: 

1ST: = TTY: 

The current logical to physical device assignment can be changed by typina a 
STAT command of the form 

STAT ldl * pdl, ld2 = pd2 , ... , ldn = pdn cr 

where ldl through ldn are logical device names, and pdl through pdn are 
compatible physical device names (i.e., ldi and trii appear on the same line in 
the "VAL:" command shown above). The following are valid STAT commands which 
change the current logical to physical device assignments: 

STAT CDN:=CRT: cr 

STAT PUN: = TTY:,LST:=LPT:, RDR:=TTY: cr 


6.2. ASM ufn cr 

The ASM command loads and executes the CP/M 8080 assembler. The ufn 
specifies a source file containing assembly language statements where the 
secondary name is assumed to be ASM, and thus is not specified. The following 
ASM commands are valid: 

ASM X 

ASM GAMMA 

The two-pass assembler is automatically executed. If assembly errors occur 
during the second pass, the errors are printed at the console. 

The assembler produces a file 

x.PRN 

where x is the primary name specified in the ASM command. The PRN file 
contains a listing of the source program (with imbedded tab characters if 
present in the source program), along with the machine code generated for each 
statement and diagnostic error messages, if any. The PRN file can be listed 


16 





at the console usinq the TYPE command, or sent to a peripheral device usinq 
PIP (see the PIP command structure below). Note also that the PRN file 
contains the original source program, augmented by miscellaneous assembly 
information in the leftmost 16 columns (program addresses and hexadecimal 
machine code, for example). Thus, the PRN file can serve as a backup for the 
original source file: if the source file is accidently removed or destroyed, 
the PRN file car. be edited (see the ED operator's guide) by removing the 
leftmost 16 characters of each line (this can be done by issuing a single 
editor "macro" command). The resulting file is identical to the original 
source file and can be renamed (REN) from PRN to ASM for subsequent editing 
and assembly. The file 

x. HEX 

is also produced which contains 8080 machine language in Intel "hex" format 
suitable for subsequent loading and execution (see the LOAD command). For 
complete details of CP/M's assembly language proqram, see the "CP/M Assembler 
Language (ASM) User s Guide." 

Similar to other transient commands, the source file for assembly can be 
taken fran an alternate disk by prefixing the assembly language file name by a 
disk drive name. Thus, the command 

ASM B:ALPHA cr 

loads the assembler from the currently logged drive and operates upon the 
source program ALPHA.ASM on drive B. The HEX and PRN files are also placed on 
drive B in this case. 


6.3. LOAD ufn cr 

The LOAD command reads the file ufn, vbich is assumed to contain 1 hex 
format machine code, and . produces a memory image file which can be 
subsequently executed. The file name ufn is assumed to be of the form 

x.HEX 

and thus only the name x need be specified in the command. The LOAD command 
creates a file named 

x.OOM 

which marks it as containing machine executable code. The file is actually 
loaded into memory and executed when the user types the file name x 
immediately after the prompting character ">" printed by the CCP. 

In general, the CCP reads the name x following the prompting character 
and looks for a built-in function name. If no function name is found, the CCP 
searches the system disk directory for a file by the name 
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x.ODM 


If found, the machine code is loaded into the TPA, and the proqram executes. 
Thus, the user need only LOAD a hex file once; it can be subsequently 
executed any number of times by simply typing the primary name. In this way, 
the user can "invent" new commands in the CCP. (Initialized disks contain the 
transient commands as (DM files, which can be deleted at the user's option.) 
The operation can take place on an alternate drive if the file name is 
prefixed by a drive name. Thus, 

LOAD B:BETA 

brinqs the LOAD program into the TPA from the currently logged disk and 
operates upon drive B after execution begins. 

It must be noted that the BETA.HEX file must contain valid Intel format 
hexadecimal machine code records (as produced by the ASM program, for example) 
which beqin at 100H, the beginning of the TPA. Further, the addresses in the 
hex records must be in ascending order; gaps in unfilled memory regions are 
filled with zeroes by the LOAD command as the hex records are read. Thus, 
LOAD must be used only for creating CP/M standard "(DM" files which operate in 
the TPA. Programs which occupy regions of memory other than the TPA can be 
loaded under DDT. 


6.4. PIP cr 

PIP is the CP/M Peripheral Interchange Program which implements the basic 
media conversion operations necessary to load, print, punch, copy, and combine 
disk files. The PIP program is initiated by typing one of the following forms 

(1) PIP cr 

(2) PIP "command line" cr 

In both cases, PIP is loaded into the TPA and executed. In case (1) , PIP 

reads command lines directly from the console, prompted with the 
character, until an empty command line is typed (i.e., a single carriage 
return is issued by the operator). Each successive command line causes some 
media conversion to take place according to the rules shown below. Form (2) 
of the PIP command is equivalent to the first, except that the single command 
line given with the PIP command is automatically executed, and PIP terminates 
immediately with no further prompting of the console for input command lines. 
The form of each command line is 

destination = source#l, source#2, ... , sourcetn cr 
where "destination" is the file or peripheral device to receive the data, and 
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c 



" 90 urce#l, ..., sourcefn" represents a series of one or more files or devices 
which are copied from left to riqht to the destination. 

When multiple files are qiven in the command line (i.e, n > 1) , the 
individual files are assumed to contain ASCII characters, with an assumed CP/M 
end-of-file character (ctl-Z) at the end of each file (see the 0 Darameter to 
override this assumption). The equal symbol (=) can be replaced by a 
left-oriented arrow, if your console supports this ASCII character, to improve 
readability. Lower case ASCII alphabetics are internally translated to upper 
case to be consistent with CP/M file and device name conventions. Finally, 
the total command line lenqth cannot exceed 255 characters (ctl-E can be used 
to force a physical carriaqe return for lines which exceed the console width). 


The destination and source elements can be unambiquous references to CP/M 
source files, with or without a preceding disk drive name. That is, any file 
can be referenced with a preceding drive name (A:, B:, C:, or D:) which 
defines the particular drive where the file may be obtained or stored. When 
the drive name is not included, the currently loqqed disk is assumed. 
Further, the destination file can also appear as one or more of the source 
files, in which case the source file is not altered until the entire 
concatenation is complete. If the destination file already exists, it is 
removed if the command line is properly formed (it is not removed if an error 
condition arises). The following command lines (with explanations to the 
riqht) are valid as input to PIP: 

X = y cr Copy to file X from file Y, 

where X and Y are unambiquous 
file names; Y remains unchanqed. 

X = Y,Z cr Concatenate files Y and Z and 

copy to file X, with Y and Z 
unchanqed. 


X.ASM=Y.ASM,Z.ASM,FIN.ASM cr 


NEW.ZOT = BsOLD.ZAP cr 


B:A.U = B:B.V,A:C.W,D.X cr 


Create the file X.ASM from the 
concatenation of the Y, Z, and 
FIN files with type ASM. 

Move a copy of OLD.ZAP from drive 
B to the currently loqqed disk; 
name the file NEW.ZOT. 

Concatenate file B.V from drive B 
with C.W from drive A and D.X. 
from the logged disk; create 
the file A.U on drive B. 



For more convenient use, PIP allows abbreviated commands for transferrinq 
files between disk drives. The abbreviated forms are 
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PIP x:=afn cr 


PIP x:=y:afn cr 
PIP ufn = y: cr 
PIP x:ufn = y: cr 

The first form copies all files from the currently loqged disk which satisfy 
the afr to the same file names on drive x (x = A...Z). The second form is 
equivalent to the first, vrtiere the source for the copy is drive y (y = A... 
Z). The third form is equivalent to the command "PIP ufn=y:ufn cr" which 
copies the file given by ufn from drive y to the file ufn on drive x. The 
fourth form is equivalent to the third, where the source disk is explicitly 
qiven by y. 

Note that the source and destination disks must be different in all of 
these cases. If an afn is specified, PIP lists each ufn which satisfies the 
afn as it is being copied. If a file exists by the same name as the 
destination file, it is removed uoon successful completion of the copy, and 
replaced by the copied file. 

The following PIP commands give examples of valid disk-to-disk copy 
operations: 


B:=*.CDM cr 


A:=B:ZAP.* cr 


ZAP.ASM=B: cr 
B:ZOT. CDM=A: cr 
B:=GAMMA.BAS cr 
B:=A:GAMMA.BAS cr 


Copy all files vrtiich have the 
secondary name "OOM" to drive B 
from the current drive. 

Copy all files vhich have the 
primary name "ZAP" to drive A 
from drive B. 

Equivalent to ZAP.ASM=B:ZAP.ASM 
Equivalent to B:ZOT.ODM=A:ZOT.COM 
Same as BiGAMMA.BAS=GAMMA.BAS 
Same as B:GAMMA.BAS=A:GAMMA.BAS 


PIP also allows reference to Dhysical and logical devices which are 
attached to the CP/M system. The device names are the same as given under the 
STAT command, along with a number of specially named devices. The logical 
devices given in the STAT command are 


CON: (console), RDR: (reader), PUN: (punch), and I£T: (list) 
while the physical devices are 
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TTY: (console, reader, punch, or list) 

CRT: (console, or list) , UC1: (console) 

FTR: (reader), URl: (reader), UR2: (reader) 

PTP: (punch), UP1: (punch), UP2: (punch) 

LPT: (list), UL1: (iist) 

(Note that the "BAT:" physical device is not included, since this assignment 
is used only to indicate that the RDR: and LST: devices are to be used for 
console input/output.) 

The RDR, 1ST, PUN, and CON devices are all defined within the BIOS 
portion of CP/M, and thus are easily altered for any particular I/O system. 
(The air rent physical device mappinq is defined by IOBYTE; see the "CP/M 
Interface Guide" for a discussion of this function). The destination device 
must be capable of receivinq data (i.e., data cannot be sent to the punch), 
and the source devices must be capable of qeneratinq data (i.e., the LST: 
device cannot be read). 

The additional device names which can be used in PIP commands are 

NUL: Send 40 "nulls" (ASCII 0's) to the device 

(this can be issued at the end of punched output). 

EOF: Send a CP/M end-of-file (ASCII ctl-Z) to the 

destination device (sent automatically at the 
end of all ASCII data transfers through PIP). 

IMP: Special PIP input source which can be "patched" 

into the PIP proqram itself: PIP qets the input 
data character-by-character by CALLinq location 
103H, with data returned in location 109H (parity 
bit must be zero). 

OUT; Special PIP output destination which can be 

patched into the PIP proqram: PIP CALLS location 
106H with data in reqister C for each character 
to transmit. Note that locations 109H throuqh 
1FFH of the PIP memory image are not used and 
can be replaced by special purpose drivers using 
DDT (see the DDT operator's manual). 

PRN: same as LST:, except that tabs are expanded at 

every eighth character position, lines are 
numbered, and page ejects are inserted every 60 
lines, with an initial eject (same as [t8npl). 


File and device names can be interspersed in the PIP commands. In each 
case, the specific device is read until end-of-file (ctl-Z for ASCII files, 
and a real end of file for non-ASCII disk files). Data frcm each device or 
file is concatenated from left to right until the last data source has been 
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read. The destination device or file is written using the data from the 
source files, and an end-of-file character (ctl-Z) is appended to the result 
for ASCII files. Note if the destination is a disk file, then a temporary 
file is created ($$$ secondary name) which is changed to the actual file name 
only upon successful completion of the copy. Files with the extension "(DM" 
are always assumed to be non-ASCII. 


The copy operation can be aborted at any time by depressing any key on 
the keyboard (a rubout suffices). PIP will respond with the message "ABORTED" 
to indicate that the operation was not completed. Note that if any operation 
is aborted, or if an error occurs during processing, PIP removes any pending 
commands which were set up while using the SUBMIT command. 


It should also be noted that PIP performs a special function if the 
destination is a disk file with type "HEX" (an Intel hex formatted machine 

code file) , and the source is an external peripheral device, such as a paper 

tape reader. In this case, the PIP program checks to ensure that the source 

file contains a properly formed hex file, with legal hexadecimal values and 

checksum records. When an invalid input record is found, PIP reports an error 
message at the console and waits for corrective action. It is usually 

sufficient to cpen the reader and rerun a section of the tape (pull the tape 
back about 20 inches). When the tape is ready for the re-read, type a single 
carriage return at the console, and PIP will attempt another read. If the 

tape position cannot be properly read, simply continue the read (by typing a 

return following the error message), and enter the record manually with the ED 
program after the disk file is constructed. For convenience, PIP allows the 
end-of-file to be entered from the console if the source file is a RDR: 

device. In this case, the PIP program reads the device and monitors the 
keyboard. If ctl-Z is typed at the keyboard, then the read operation is 
terminated normally. 

Valid PIP commands are shown below. 


PIP I£T: = X.PRN cr 


PIP cr 

*CDN:=X.ASM,Y.ASM,Z.ASM cr 


*X.HEX=CON:,Y.HEX,PTR: cr 


*cr 


Copy X.PRN to the LST device and 
terminate the PIP proaram. 

Start PIP for a sequence of 
ccmmands (PIP prompts with "*"). 

Concatenate three ASM files and 
copy to the CON device. 

Create a HEX file by reading the 
CDN (until a ctl-Z is typed), fol¬ 
lowed by data from Y.HEX, followed 
by data from FTR until a ctl-Z is 
encountered. 

Single carriage return stops PIP. 
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PIP PUN:=NUL: ,X.ASM,EOF:,NUL: cr Send 40 nulls to the punch device; 

then copy the X.ASM file to the 
punch, followed by an end-of-file 
(ctl-Z) and 40 more null charac¬ 
ters. 

The user can also specify one or more PIP parameters, enclosed in left 
and riqht square brackets, separated by zero or more blanks. Each parameter 
affects the copy operation, and the enclosed list of parameters must 
immediately follow the affected file or device. Generally, each parameter can 
be followed by an optional decimal inteqer value (the S and 0 parameters are 
exceptions). The valid PIP parameters are listed below. 

B Block mode transfer; data is buffered by PIP until an ASCII 

x-off character (ctl-S) is received from the source device. 
This allows transfer of data to a disk file from a continuous 
readinq device, such as a cassette reader. Upon receipt of 
the x-off, PIP clears the disk buffers and returns for more 
input data. The amount of data which can be buffered is de¬ 
pendent upon the memory size of the host system (PIP will 
issue an error message if the buffers overflow). 

Dn Delete characters which extend past column n in the transfer 
of data to the destination from the character source. This 
parameter is used most often to truncate long lines which are 
sent to a (narrow) printer or console device. 

E Echo all transfer operations to the console as they are being 

performed. 

F Filter form feeds from the file. All imbedded form feeds are 

removed. The P parameter can be used simultaneously to 
insert new form feeds. 

H Hex data transfer: all data is checked for proper Intel hex 

file format. Non-essential characters between hex records 
are removed during the copy operation. The console will be 
prompted for corrective action in case errors occur. 

I Ignore ,, :00" records in the transfer of Intel hex format 

file (the I parameter automatically sets the H parameter). 

L Translate upper case alphabetics to lower case. 

N Add line numbers to each line transferred to the destination 

starting at one, and incrementing by 1. Leading zeroes are 
suppressed, and the number is followed by a colon. If N2 
is specified, then leadinq zeroes are included, and a tab is 
inserted following the number. The tab is expanded if T is 
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set. 


0 Object file (non-ASCII) transfer: the normal CP/M end of 
file is ignored. 

Pn Include paqe ejects at every n lines (with an initial paqe 
eject). If n = 1 or is excluded altogether, paqe ejects 
occur every 60 lines. If the F parameter is used, form feed 
suppression takes place before the new paqe ejects are 
inserted. 

Qs r z Ckit copying from the source device or file when the 
string s (terminated by ctl-Z) is encountered. 

Ss f z Start copyinq from the source device when the strinq s is 
encountered (terminated by ctl-Z). The S and 0 parameters 
can be used to "abstract" a particular section of a file 
(such as a subroutine). The start and auit strings are al¬ 
ways included in the copy operation. 

NOTE - the strings following the s and g parameters are 
translated to upper case by the CCP if form (2) of the 
PIP command is used. Form (1) of the PIP invocation, how¬ 
ever, does not perform the automatic upper case translation. 

(1) PIP cr 

(2) PIP "command line" cr 

Tn Expand tabs (ctl-I characters) to every nth column durinq the 
transfer of characters to the destination from the source. 

U Translate lower case alphabetics to upper case during the 
the copy operation. 

V Verify that data has been copied correctly by rereading 

after the write operation (the destination must be a disk 
file). 

Z Zero the parity bit on input for each ASCII character. 


The following are valid PIP commands which specify parameters in the file 
transfer: 

PIP X.ASM=B: [v] cr Copy X.ASM from drive B to the current drive 

and verify that the data was properly copied. 

PIP LPT:=X.ASM[nt8u] cr Copy X.ASM to the LPT: device; nuntoer each 

line, expand tabs to every eiqhth column, and 
translate lower case alphabetics to upper 
case. 
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PIP PUN:=X.HEX[i],Y.ZOT[h] cr First copy X.HEX to the PUN: device and 

ignore the trailing ":00" record in X.HEX; 
then continue the transfer of data by reading 
Y.ZOT, which contains hex records, including 
any ":00" records which it contains. 

PIP X.LIB = Y.ASM [ sSUBRl: f z qJMP L3 T z ] cr Copy from the file Y.ASM 

into the file X.LIB. Start the copy when the 
string "SUBR1:" has been found, and quit copy- 
inq after the string "JMP L3" is encountered. 


PIP PRN:=X.ASM[p50) Send X.ASM to the LST: device, with line num¬ 

bers, tabs expanded to every eighth column, 
and page ejects at every 50th line. Note that 
nt8p60 is the assumed parameter list for a PRN 
file; p50 overrides the default value. 


6.5. ED ufn cr 


The ED program is the CP/M system context editor, which allows creation 
and alteration of ASCII files in the CP/M environment. Complete details of 
operation are given the ED user s manual, “ED: a Context Editor for the CP/M 
Disk System." In general, ED allows the operator to create and operate upon 
source files which are organized as a sequence of ASCII characters r separated 
by end-of-line characters (a carriage-return line-feed seauence). There is no 
practical restriction on line lenqth (no sinqle line can exceed the size of 
the working memory), which is instead defined by the number of characters 
typed between cr's. The ED program has a number of commands for character 
string searching, replacement, and insertion, which are useful in the creation 
and correction of programs or text files aider CP/M. Although the CP/M1 has a 
limited memory work space area (approximately 5000 characters in a 16K CP/M 
system) , the file size which can be edited is not limited, since data is 
easily "paged" through this work area. 


Upon initiation, ED creates the specified source file, if it does not 
exist, and opens the file for access. The programmer then "appends" data from 
the source file into the work area, if the source file already exists (see the 
A command), for editing. The appended data can then be displayed, altered, 
and written from the work area back to the disk (see the W command). 
Particular points in the program can be automatically paged and located by 
context (see the N command), allowing easy access to particular portions of a 
large file. 


Given that the operator has tvped 


ED X.ASM cr 
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the ED program creates an intermediate work file with the name 

X.$$$ 

to hold the edited data during the ED run. upon completion of ED, the X.ASM 
file (original file) is renamed to X.BAK, and the edited work file is renamed 
to X.ASM. Thus, the X.BAK file contains the oriainal (unedited) file, and the 
X.ASM file contains the newly edited file. The operator can always return to 
the previous version of a file by removing the most recent version, and 
renaming the previous version. Suppose, for example, that the current X.ASM 
file was improperly edited; the sequence of CCP command shown below would 
reclaim the backup file. 

DIR X.* Check to see that BAK file 

is available. 

ERA X.ASM Erase most recent version. 

REN X.ASM=X.BAK Rename the BAK file to ASM. 


Note that the operator can abort the edit at any point (reboot, power failure, 
ctl-C, or 0 command) without destroying the original file. In this case, the 
BAK file is not created, and the original file is always intact. 

The ED program also allows the user to “ping-pong" the source and create 
backup files between two disks. The form of the ED canmand in this case is 

ED ufn d; 

where ufri is the name of a file to edit on the currently logged disk, and d is 
the name of an alternate drive. The ED program reads and processes the source 
file, and writes the new file to drive d, using the name ufn. Upon completion 
of processing, the original file becomes the backup file. Thus, if the 
operator is addressing disk A, the following command is valid: 


ED X.ASM B: 

v*iich edits the file X.ASl on drive A, creating the new file X.$$$ on drive 
u Jf n . completion of a successful edit, ArX.ASM is renamed to ArX.BAK, and 
B:X.$$$ is renamed to B:X.ASM. For user convenience, the currently logged 
disk becomes drive B at the end of the edit. Note that if a file by the name 
BrX.ASM exists before the editing begins, the message 

FILE EXISTS 


is printed at the console as a precaution against 
source file. In this case, the operator must first 
and then restart the edit operation. 


accidently destroying a 
ERAse the existing file 


26 








Similar to other transient commands, editing can take place on a drive 
different frcm the currently logged disk by preceding the source file name by 
a drive name. Examples of valid edit requests are shown below 

ED A:X.ASM Edit the file X.ASM on drive A, with 

new file and backup on drive A. 

ED B:X.ASM A: Edit the file X.ASM on drive B to the 

temporary file X.$$$ on drive A. On 
termination of editing, change X.ASM 
on drive B to X.BAK, and chanqe X.$$S 
on drive A to X.ASM. 


6.6. SYSGEN cr 

The SYSGEN transient command allows generation of an initialized diskette 
containing the CP/M operating system. The SYSGEN program prompts the console 
for commands, with interaction as shown below. 

SYSGEN cr Initiate the SYSGEN program. 

SYSGEN VERSION m.m SYSGEN sign-on messaqe. 

SOURCE DRIVE NAME (OR RETURN TO SKIP) 

Respond with the drive name (one 
of the letters A, B, C, or D) of 
the disk containing a CP/M sys¬ 
tem; usually A. If a copy of 
CP/M already exists in memory, 
due to a MOVCPM command, type a 
cr only. Typing a drive name 
x will cause the response: 

SOURCE ON x THEN TYPE RETURN Place a diskette containing the 

CP/M operating system on drive 
x (x is one of A, B, C, or D). 
Answer with cr vhen ready. 

FUNCTION COMPLETE System is copied to memory. 

SYSGEN will then prompt with: 

DESTINATION DRIVE NAME (OR RETURN TO REBOOT) 

If a diskette is being ini¬ 
tialized, place the new disk 
into a drive and answer with 
the drive name. Otherwise, type 
a cr and the system will reboot 
from drive A. Typinq drive name 
x will cause SYSGEN to prompt 


* 
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with: 


DESTINATION ON x THEN TYPE RETURN Place new diskette into drive 

x; type return when ready. 

FUNCTION COMPLETE New diskette is initialized 

in drive x. 

The "DESTINATION" prompt will be repeated until a single carriage return is 
typed at the console, so that more than one disk can be initialized. 


Upon camoletion of a successful system generation, the new diskette 
contains the operating system, and only the built-in commands are available. 
A factory-fresh IBM-corrpatible diskette appears to CP/M as a diskette with an 
empty directory; therefore, the operator must copy the appropriate 00M files 
from an existing CP/M diskette to the newly constructed diskette using the PIP 
transient. 

The user can copy all files from an existing diskette by typing the PIP 
command 


PIP B: = A: *.*(vj cr 

which copies all files from disk drive A to disk drive B, and verifies that 
each file has been copied correctly. The name of each file is displayed at 
the console as the copy operation proceeds. 

It should be noted that a SYSGEN does not destroy the files which already 
exist on a diskette; it results only in construction of a new operating 
system. Further, if a diskette is being used only on drives B through D, and 
will never be the source of a bootstrap operation on drive A, the SYSGEN need 
not take place. In fact, a new diskette needs absolutely no initialization to 
be used with CP/M. 


6.7. SUBMIT ufn parm#l ... parm#n cr 

The SUBMIT command allows CP/M commands to be batched together for 
automatic processing. The ufn given in the SUBMIT command must be the 
filename of a file vtoich exists on the currently logged disk, with an assumed 
file type of "SUB." The SUB file contains CP/M prototype commands, with 
possible parameter sifcstitution. The actual parameters parmtl ... parm#n are 
substituted into the prototype commands, and, if no errors occur, the file of 
substituted commands are processed sequentially by CP/M. 
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The prototype command file is created using the ED program, with 

interspersed "$" parameters of the form 

$1 $2 $3 ... $n 

corresponding to the number of actual parameters which will be included when 
the file is sifomitted for execution. When the SUBMIT transient is executed, 
the actual parameters parm#l ... parm#n are paired with the formal parameters 
$1 ... $n in the prototype commands. If the number of formal and actual 
parameters does not correspond, then the submit function is aborted with an 
error message at the console. The SUBMIT function creates a file of 
substituted commands with the name 

$$$.SUB 

on the logged disk. When the system reboots (at the termination of the 
SUBMIT), this command file is read by the CCP as a source of input, rather 
than the console. If the SUBMIT function is performed on any disk other than 

drive A, the commands are not processed until the disk is inserted into drive 

A and the s'/Stan reboots. Further, the user can abort command processing at 
any time by typina a rubout when the command is read and echoed. In this 
case, the $$$.SUB file is removed, and the subsequent canmands cone from the 
console. Command processing is also aborted if the CCP detects an error in 
any of the commands. Proqrams which execute under CP/M can abort processing of 
command files when error conditions occur by simply erasing any existing 
$$$.SUB file. 

In order to introduce dollar signs into a SUBMIT file, the user may type 
a "$$" which reduces to a single "$" within the command file. Further, an 
up-arrow symbol may precede an alphabetic character x, which produces a 
single ctl-x character within the file. 

The last command in a SUB file can initiate another SUB file, thus 
allowing chained batch commands. 

Suppose the file ASMBL.SUB exists on disk and contains the prototype 
commands 

ASM $1 
DIR $1.* 

ERA *.BAK 
PIP $2:=$1.PRN 
ERA $1.PRN 

and the command 

SUBMIT ASMBL X PRN cr 

is issued by the operator. The SUBMIT program reads the ASMBL.SUB file, 
sihstituting "X" for all occurrences of $1 and "PRN" for all occurrences of 
$2, resulting in a $$$.SUB file containing the commands 


29 






ASM X 
DIR X.* 

ERA *.BAK 
PIP PRN:=X.PRN 
ERA X.PRN 

which are executed in sequence by the CCP. 

The SUBMIT function can access a SUB file which is on an alternate drive 
by preceding the file name by a drive name. Submitted files are only acted 
upon, however, when they appear on drive A. Thus, it is possible to create a 
submitted file on drive B vfruch is executed at a later time when it is 
inserted in drive A. 


6.8. DUMP ufn cr 

The DUMP proqram types the contents of the disk file (ufn) at the console 
in hexadecimal form. The file contents are listed sixteen bytes at a time, 
with the absolute byte address listed to the left of each line in 
hexadecimal. Long typeouts can be aborted by pushing the rubout key during 
printout. (The source listing of the DUMP program is given in the "CP/M 
Interface Guide" as an example of a proqram written for the CP/M environment.) 


6.9. MOVCPM cr 

The MOVCPM proqram allows the user to reconfigure the CP/M system for any 
particular memory size. Two optional parameters may be used to indicate (1) 
the desired size of the new system and (2) the disposition of the new system 
at program termination. If the first parameter is emitted or a is given, 
the MOVCPM program will reconfigure the system to its maximum size, based upon 
the kilobytes of contiguous RAM in the host system (starting aat 0000H). If 
the second parameter is omitted, the system is executed, but not permanently 
recorded; if is qiven, the system is left in memory, ready for a SYSGEN 
operation. The MOVCPM program relocates a memory image of CP/M and places 
this imaqe in memory in preparation for a system generation operation. The 
command forms are: 

MOVCPM cr Relocate and execute CP/M for manage¬ 

ment of the current memory configura¬ 
tion (memory is examined for contigu¬ 
ous RAM, starting at 100H). Upon com¬ 
pletion of the relocation, the new 
system is executed but not permanently 
recorded on the diskette. The system 
which is constructed contains a BIOS 
for the Intel MDS 800. 
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MOVCPM n cr 


MOVCPM * * cr 


MOVCPM n * cr 


Create a relocated CP/M system for 
manaqement of an n kilobyte system (n 
must be in the ranqe 16 to 64), and 
execute the system, as described above. 

Construct a relocated memory image for 
the current memory configuration, but 
leave the memory image in memory, in 
preparation for a SYSGEN operation. 

Construct a relocated memory image for 
an n kilobyte memory system, and leave 
the memory image in preparation for a 
SYSGEN operation. 


The command 

MOVCPM * * 

for example, constructs a new version of the CP/M system and leaves it in 
memory, ready for a SYSGEN operation. The message 


READY FOR "SYSGEN" OR 
"SAVE 32 CPMxx.OOM" 


is printed at the console upon completion, where xx is the current memory size 
in kilobytes. The operator can then type 

SYSGEN cr Start the system generation. 

SOURCE ERIVE NAME (OR RETURN TO SKIP) Respond with a cr to skip 

the CP/M read operation since the system 
is already in memory as a result of the 
previous MOVCPM operation. 

DESTINATION ERIVE NAME (OR RETURN T0 REBOOT) 

Respond with B to write new system 
to the diskette in drive B. SYSGEN 
will prompt with: 


DESTINATION ON B, THEN TYPE RETURN 

Ready the fresh diskette on drive 
B and type a return when ready. 

Note that if you respond with "A" rather than "B" above, the system will be 
written to drive A rather than B. SYSGEN will continue to type the prompt: 

DESTINATION ERIVE NAME (OR RETURN TO REBOOT) 

until the operator responds with a single carriage return, which stops the 
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SYSGEN program with a system reboot 


The user can then go through the reboot process with the 
old or new diskette. Instead of performing the SYSGEN 
operation, the user could have typed 


SAVE 32 CPMxx.COM 


at the completion of the MOVCP function, which would place the 
CP/M memory image on the currently logged disk in a form which 
can be patched". This is necessary when operating in a non- 
standard environment where the BIOS must be altered for a 
particular peripheral device configuration, as described in the 
CP/M System Alteration Guide". 

Valid MOVCP commands are given below: 


MOVCPM 48 cr 

MOVCPM 48 * cr 


MOVCPM * * CR 


Construct a 48K version of CP/M 
and start execution 

Construct a 48K version of CP/M 
in preparation for permanent re¬ 
cording; response is 

READY FOR "SYSGEN" OR 
"SAVE 32 CPM48.COM" 

Construct a maximum memory 
version of CP/M and start execu 
t ion. 


It is important to note that the newly 
serialized with the number attached to the 
and is subject to the conditions of the Exidy Inc. 
Licensing Agreement. 


created system is 
original diskette 
Software 
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7. BDOS ERROR MESSAGES. 

There are three error situations which the Basic Disk Operatinq System 
intercepts during file processsing. When one of these conditions is detected, 
the BDOS prints the nessage: 

BDOS ERR ON x: error 

where x is the drive name, and "error" is one of the three error messaqes: 

BAD SECTOR 
SELECT 
READ ONLY 

The "BAD SECTOR" message indicates that the disk controller electronics 
has detected an error condition in reading or writing the diskette. This 
condition is generally due to a malfunctioning disk controller, or an 
extremely worn diskette. If you find that your system reports this error more 
than once a month, you should check the state of your controller electronics, 
and the condition of your media. You may also encounter this condition in 
reading files generated by a controller produced by a different manufacturer. 
Even though controllers are claimed to be IBM-compatible, one often finds 
small differences in recording formats. The MES-800 controller, for example, 
requires two bytes of one s following the data CRC byte, which is not required 
in the IBM format. As a result, diskettes generated by the Intel MD6 can be 
read by almost all other IBM-compatible systems, while disk files generated on 
other manufacturer's equipment will produce the "BAD SECTOR" message when read 
by the MES. In any case, recovery from this condition is accomplished by 
typing a ctl-C to reboot (this is the safest!) , or a return, which simply 
ignores the bad sector in the file operation. Note, however, that typing a 
return may destroy your diskette integrity if the operation is a directory 
write, so make sure you have adequate backups in this case. 

The "SELECT" error occurs when there is an attempt to address a drive 
beyond the A through D range. In this case, the value of x in the error 
message gives the selected drive. The system reboots following any input from 
the console. 

The "READ ONLY" message occurs when there is an attempt to write to a 
diskette which has been designated as read-only in a STAT command, or has been 
set to read-only by the BDOS. In general, the operator should reboot CP/M 
either by using the warm start procedure (ctl-C) or by performing a cold start 
whenever the diskettes are changed. If a changed diskette is to be read but 
not written, BDOS allows the diskette to be changed without the warm or cold 
start, but internally marks the drive as read-only. The status of the drive 
is subsequently changed to read/write if a warm or cold start occurs. Upon 
issuing this message, CP/M waits for input from the console. An automatic 
warm start takes place following any input. 
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8. OPERATION OF CP/M ON THE MD6. 


Tnis section gives cperatinq procedures for using CP/M on the Intel ME6 
microcomputer development system. A basic knowledge of the MEG hardware and 
software systems is assumed. 

CP/M is initiated in essentially the same manner as Intel's ISIS 
operating system. The disk drives are labelled 0 through 3 on the MEG, 

corresponding to CP/M drives A through D, respectively. The CP/M system 
diskette is inserted into drive 0, and the BOOT and RESET switches are 
depressed in sequence. The interrupt 2 light should go on at this point. The 
space bar is tnen depressed on the device which is to be taken as the system 
anb bbe ^^ht should go out (if it does not, then check connections 
and baud rates). The BOOT switch is then turned off, and the CP/M signon 
message should appear at the selected console device, followed by the "A>" 

system prompt. The user can then issue the various resident and transient 
commands 


TMm J he CP/M system can be restarted (warm start) at any time by pushing the 
INT 0 switch on the front panel. The built-in Intel ROM monitor can be 
initiated by pushing the INT 7 switch (which generates a RST 7) , except when 
operating inder DET, in which case the DDT program gets control instead. 

Diskettes can be renoved from the drives at any time, and the system can 
be shut down during operation without affecting data integrity Note 
however, that the user must not remove a diskette and replace it with another 

without rebooting the system (cold or warm start), unless the inserted 
diskette is read only." 


Cue to hardware hang-ups or malfunctions, CP/M may type the message 
BDOS ERR ON x: BAD SECTOR 


where x is the drive which has a permanent error. This error may occur whei 
drive doors are opened and closed randomly, followed by disk operations, oi 
may be due to a diskette, drive, or controller failure. The user cat 
optionally elect to ignore the error by typing a single return at th< 
console. The error may produce a bad data record, requiring re-initializatior 

Of up to 128 bytes of data. The operator can reboot the CP/M system and tn 
the operation again. J 


Termination of a CP/M session requires no special action, except that it 
is necessary to remove the diskettes before turning the power off, to avoid 
random transients which often make their way to the drive electronics. 


!t should be noted that factory-fresh IBM-compatible diskettes should be 
used rather than diskettes which have previously been used with any ISIS 
version. in particular, the ISIS "FORMAT" operation produces non-standard 
sector numbering throughout the diskette. This non-standard numbering 
seriously degrades the performance of CP/M, and will operate noticeably slower 
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than the distribution version. If it becomes necessary to reformat a diskette 
(which should not be the case for standard diskettes), a program can be 
written inder CP/M vrtiich causes the ME6 800 controller to reformat with 
sequential sector numbering (1-26) on each track. 


Note: "MD6 800“ and "ISIS" are registered trademarks of Intel Corporation. 
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CP/M INTERFACE GUIDE 


1. INTRODUCTION 

This manual describes the CP/M system organization including 
the structure of memory, as well as system entry points. The 
intention here is to provide the necessary information required 
to write programs which operate under CP/M, and which use the 
peripheral and disk I/O facilities of the system. 

1.1 CP/M Organization 

CP/M is logically divided into four parts: 

BIOS - the basic I/O system for serial peripheral control 
BDOS - the basic disk operating system primitives 
CCP - the console command processer 
TPA - the transient program area 


The BIOS and BDOS are combined into a single program with a com¬ 
mon entry point and referred to as the FDOS. The CCP is a dis- 
tinct program which uses the FDOS to provide a human-oriented 
interface to the information which is cataloged on the diskette. 

The TPA is an area of memory (i.e, the portion which is not use 
by the FDOS and CCP) where various non-resident operating system 
commands are executed. User programs also execute in the TPA. 

The organization of memory in a standard CP/M system is s own m 

F ' g The lower portion of memory is reserved for system information 
(which is detailed in later sections), including user defined inter¬ 
rupt locations. The portion between tbase and cbase is reserved 
for the transient operating system commands, while the P° r tion 
above cbase contains the resident CCP and FDOS. The ijstthree 
locations of memory contain a jump instruction to the FDOS entry 
point which provides access to system functions. 

1.2 Operation of Transient Programs 

Transient programs (system functions and user-defined programs) 
are loaded into the TPA and executed as follows. The operator 
communicates with the CCP by typing command lines following each 
prompt character. Each command line takes one of the form : 

( < command > 

<command> <filename> 

<command> <filename^” ,<f iletype>^ 
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Figure 1. CP/M Memory Organization 



entry: the Principal entry point to FDOS is at location 0005 
which contains a JMP to fbase. The address field at 
location 0006 can be used to determine the size of 
available memory, assuming the CCP is being overlayed. 


Not;e: The exact addresses for boot, tbase, cbase, fbase, 

and entry vary with the CP/M version (see 
Section 6. for version correspondence). 
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Where < command> is either a built-in command (e.g., DIR or TYPE), 
or the name of a transient command or program. If the <coramand> 
is a built-in function of CP/M, it is executed immediately? other¬ 
wise the CCP searches the currently addressed disk for a file 
by the name 


< command >.COM 


If the file is found, it is assumed to be a memory image of a 
program which executes in the TPA, and thus implicitly originates 
at tbase in memory (see the CP/M LOAD command). The CCP loads 
the COM file from the diskette into memory starting at .tbase, 
and extending up to address cbase. 

If the <command> is followed by either a <filename> or 
<filename>.<filetype>, then the CCP prepares a file control- 
block (FCB) in the system information area of memory. This FCB 
is in the form required to access the file through the FDOS, and 
is given in detail in Section 3.2. 

The program then executes, perhaps using the I/O facilities 
of the FDOS. If the program uses no FDOS facilities, then the 
entire remaining memory area is available for data used by the 
program. If the FDOS is to remain in memory, then the transient 
program can use only up to location fbase as data.* In any case, 
if the CCP area is used by the transient, the entire CP/M system 
must be reloaded upon the transient's completion. This system 
reload is accomplished by a direct branch to location "boot" in 
memory. 

The transient uses the CP/M I/O facilities to communicate 
with the operator's console and peripheral devices, including 
the floppy disk subsystem. The I/O system is accessed by passing 
a "function number" and an "information address" to CP/M through 
the address marked "entry" in Figure 1. In the case of a disk 
read, for example, the transient program sends the number corres¬ 
ponding to a disk read, along with the address of an FCB, and 
CP/M performs the operation, returning with either a disk read 
complete indication or an error number indicating that the disk 
operation was unsuccessful. The function numbers and error in¬ 
dicators are given in detail in Section 3.3. 

1.3 Operating System Facilities 

CP/M facilities which are available to transients are divided 
into two categories: BIOS operations, and BDOS primitives. The 
BIOS operations are listed first:** 


* Address "entry" contains a jump to the lowest address in the 
FDOS, and thus "entry+1" contains the first FDOS address which 
cannot be overlayed. 

**The device support (exclusive of the disk subsystem) corres¬ 
ponds exactly to Intel's peripheral definition, including I/O 
port assignment and status byte format (see the Intel manual 
which discusses the Intellec MDS hardware environment). 
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Read Console Character 
Write Console Character 
Read Reader Character 
Write Punch Character 
Write List Device Character 
Set I/O Status 
Interrogate Device Status 
Print Console Buffer 
Read Console Buffer 
Interrogate Console Status 

The exact details of BIOS access are given in Section 2. The BDOS 
primitives include the following operations: 

Disk System Reset 
Drive Select 
File Creation 
File Open 
File Close 
Directory Search 
File Delete 
File Rename 
Read Record 
Write Record 

Interrogate Available Disks 
Interrogate Selected Disk 
Set DMA Address 


The details of BDOS access are given in Section 3. 


2. BASIC I/O FACILITIES 

Access to common peripherals is accomplished by passing a 
function number and information address to the BIOS. In general, 
the function number is passed in Register C, while the informa¬ 
tion address is passed in Register pair D,E. Note that this 
conforms to the PL/M Conventions for parameter passing, and thus 
the following PL/M procedure is sufficient to link to the BIOS 
when a value is returned: 


DECLARE ENTRY LITERALLY '0005H'; /* MONITOR ENTRY */ 

MON2: PROCEDURE (FUNC, INFO) BYTE; 

DECLARE FUNC BYTE, INFO ADDRESS; 

GO TO ENTRY; 


END MON2; 
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or 

M0N1: PROCEDURE (FUNC,INFO); 

DECLARE FUNC BYTE, INFO ADDRESS; 
GO TO ENTRY; 

END MON1 


if no returned value is expected. 

2.1 Direct and Buffered I/O. 

The BIOS entry points are given in Table I. In the case of 
simple character I/O to the console, the BIOS reads the console 
device, and removes the parity bit. The character is echoed back 
to the console, and tab characters (control-I) are expanded to 
tab positions starting at column one and separated by eight char¬ 
acter positions. The I/O status byte takes the form shown in 
Table I, and can be programmatically interrogated or changed. 

The buffered read operation takes advantage of the CP/M line edit¬ 
ing facilities. That is, the program sends the address of a read 
buffer whose first byte is the length of the buffer. The second 
byte is initially empty, but is filled-in by CP/M to the number 
of characters read from the console after the operation (not 
including the terminating carriage-return). The remaining posi- 
tions are used to hold the characters read from the console. The 
BIOS line editing functions which are performed during this oper¬ 
ation are given below: 


break - line delete and transmit 

rubout - delete last character typed, and echo 

control-C - system rebout 

control-U - delete entire line 

control-E - return carriage, but do not transmit 
buffer (physical carriage return) 

<cr> - transmit buffer 

The read routine also detects control character sequences other 
than those shown above, and echos them with a preceding 
symbol. The print entry point allows an entire string of symbols 
to be printed before returning from the BIOS. The string is 
terminated by a "$" symbol. 

2.2 A Simple Example 

As an example, consider the following PL/M procedures and 
procedure calls which print a heading, and successively read 
the console buffer. Each console buffer is then echoed back in 
reverse order: 
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PRINTCHAR: PROCEDURE (B); 

/* SEND THE ASCII CHARACTER B TO THE CONSOLE */ 
DECLARE B BYTE; 

CALL MON1(2,B); 

END PRINTCHAR; 


CRLF: PROCEDURE; 

/* SEND CARRIAGE-RETURN-LINE-FEED CHARACTERS */ 
CALL PRINTCHAR (0DH) ; CALL PRINTCHAR (OAH) ; 

END CRLF; 


PRINT: PROCEDURE (A); 

/* PRINT THE BUFFER STARTING AT ADDRESS A */ 

DECLARE A ADDRESS; 

CALL MON1(9,A); 

END PRINT; 

DECLARE FDBUFF (130) BYTE; 

READ: PROCEDURE; 

/* READ CONSOLE CHARACTERS INTO 'RDBUFF' */ 

RDBUFF=128; /* FIRST BYTE SET TO BUFFER LENGTH */ 

CALL MONl(10,.RDBUFF); 

END READ; 

DECLARE I BYTE; 

CALL CRLF; CALL PRINT (.'TYPE INPUT LINES $'); 

DO WHILE 1; /* INFINITE LOOP-UNTIL CONTROL-C */ 

CALL CRLF; CALL PRINTCHAR ('*'); /* PROMPT WITH '*' */ 
CALL READ; I = RDBUFF(1); 

DO WHILE (I := I -1) <> 255; 

CALL PRINTCHAR (RDBUFF(1+2)); 

END; 

END; 


The execution of this program might proceed as follows: 


TYPE INPUT LINES 
♦HELLO, 

OLLEH 

♦WALL WALLA WASH^ 
HSAW ALLAW ALLAW 
♦MOM WOW, 

WOW MOM 

*tc 


(system reboot) 
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C 


TABLE I 

BASIC I/O OPERATIONS 


FUNCTION/ 

NUMBER 

ENTRY 

PARAMETERS 

RETURNED 

VALUE 

TYPICAL 

CALL 

Read Console 

1 

None 

ASCII Character 

I = MON2(1,0) 

Write Console 

2 

ASCII Character 

None 

CALL MON1(2, 'A' ) 

Read Reader 

3 

None 

ASCII Character 

I = MON2(3,0) 

Write Punch 

4 

ASCII Character 

None 

CALL MONl(4, 1 B’ ) 

Write List 

5 

ASCII Character 

None 

CALL MONl(5, ' C ' ) 

___ 1 

Get I/O Status 

7 

None 

I/O Status Byte 

IOSTAT=MON2(7,0) 

Set I/O Status 

8 

I/O Status Byte 

None 

CALL MONl(8,IOSTAT) 

Print Buffer 

9 

Address of 
string termi¬ 
nated by ' $ ' 

None 

CALL MONl(9, .'PRINT 
THIS $') 
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TABLE I (continued) 


FUNCTION/ 

NUMBER 

ENTRY 

PARAMETERS 

RETURNED 

VALUE 

TYPICAL 

CALL 

Read Buffer 

10 

Address of 

Read Buffer* 

(See Note^) 

Read buffer is 
filled to maxi¬ 
mum length with 
console charac¬ 
ters 

CALL M0N1(10, 

.RDBUFF); 

Interroga te 
Console Ready 

11 

None 

Byte value with 
least signifi¬ 
cant bit = 1 
(true) if con¬ 
sole character 
is ready 

I = MON2(11,0) 

Note^: Read buf 

fer is a sequence of memory locations 

of the form: 

| m | k | c l c 2 

c 3 c k 



t ^-current buffer length 
•—Maximum buffer length 


Note, 


The I/O status byte is defined as three fields A,B,C, and D 

2b 2b 2b 2b 

I A | B 1 C | D 


MSB 


LSB 


requiring two bits each, listed from most significant to least 
significant bit, which define the current device assignment as 
follows: 


D 

Console 


'0 TTY ^ 

1 CRT \ 

2 BATCHj 



TTY 
FAST READER 



TTY 
FAST PUNCH 
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3. DISK I/O FACILITIES 

The a DOS section of CP/M provides access to files stored on 
diskot tes. The discussion which follows gives the overall file 
organization, along with file access mechanisms. 

3.1 File Organization 

CP/M implements a named file structure on each diskette, pro¬ 
viding a logical organization which allows any particular file to 
contain any number of records, from completely empty, to the full 
capacity of a diskette. Each diskette is logically distinct, 
with a complete operating system, disk directory, and file data 
area. The disk file names are in two parts: the < filename> 
which can be from one to eight alphanumeric characters, and the 
<fi!etype> which consists of zero through three alphanumeric 
characters. The <filetype> names the generic category of a par¬ 
ticular file, while the <filename> distinguishes a particular 
file within the category. The <filetype>s listed below give 
some generic categories which have been established, although 
they are generally arbitrary: 


ASM assembler source file 

prn assembler listing file 

HEX assembler or PL/M machine code 
in "hex" format 

BAS BASIC Source file 

INT BASIC Intermediate file 

COM Memory image file (i.e., "Command" 

file for transients, produced by LOAD) 

BAK Backup file produced by editor 
(see ED manual) 

$$$ Temporary files created and normally 
erased by editor and utilities 

Thus, the name 


X. ASM 

is interpreted as an assembly language source file by the CCP 

Wlth T hf 1 files in CP/M are organized as a logically contiguous se¬ 
quence of 128 byte records (although the records may not be phys¬ 
ically contiguous on the diskette), which are normally read or 
written in sequential order. Random access is allowed under CP/M 
however,as described in Section 3.4. No particular format with¬ 
in records is assumed by CP/M, although some transients expect 
particular formats: 
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(1) Source files are considered a sequence of 
ASCII characters, where each "line" of the 
source file is followed by carriage—return— 
line-feed characters. Thus, one 128 byte 
CP/M record could contain several logical 
lines of source text. Machine code "hex" 
tapes are also assumed to be in this for¬ 
mat, although the loader does not require 
the carriage—return—line-feed characters. 

End of text is given by the character con- 
trol-z, or real end-of-file returned by 
CP/M. 

and 

(2) COM files are assumed to be absolute machine 
code in memory image form, starting at tbase 
in memory. in this case, control-z is not 
considered an end of file, but instead is 
determined by the actual space allocated 

to the file being accessed. 

3.2 File Control Block Format 

Each file being accessed through CP/M has a corresponding 
file control block (FCB) which provides name and allocation 
information for all file operations. The FCB is a 33-byte area 
in the transient program's memory space which is set up for each 
file. The FCB format is given in Figure 2. When accessing CP/M 
files, it is the programmer's responsibility to fill the lower 
16 bytes of the FCB, along with the CR field. Normally, the FN 
and FT fields are set to the ASCII <filename> and <filetype>, 
while all other fields are set to zero. Each FCB describes up 
to 16K bytes of a particular file (0 to 128 records of 128 bytes 
each), and, using automatic mechanisms of CP/M, up to 15 addi¬ 
tional extensions of the file can be addressed. Thus, each FCB 
can potentially describe files up to 256K bytes (which is slightly 
larger than the diskette capacity). 

FCB's are stored in a directory area of the diskette, and are 
brought into central memory before file operations (see the OPEN 
and MAKE commands) then updated in memory as file operations pro¬ 
ceed, and finally recorded on the diskette at the termination of 
the file operation (see the CLOSE command). This organization 
makes CP/M file organization highly reliable, since diskette file 
integrity can only be disrupted in the unlikely case of hardware 
failure during update of a single directory entry. 

It should be noted that the CCP constructs an FCB for all 
transients by scanning the remainder of the line following the 
transient name for a <filename> or <filename>.<filetype> com¬ 
bination. Any field not specified is assumed to be all blanks. 

A properly formed FCB is set up at location tfcb (see Section 6), 
with an assumed I/O buffer at tbuff. The transient can use tfcb 
as an address in subsequent input or output operations on this 
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In addition to the default fob which is set-up at address tfcb, the 
CCP also constructs a second default fcb at address tfcb+ 16 (i.e., the 
disk map field of the fcb at tbase). Thus, if the user types 

PROGNAME X.ZOT Y.ZAP 

the file PROGNAME.COM is loaded to the TPA, and the default fcb at tfcb 
is initialized to the filename X with filetype ZOT. Since the user typed 
a second file name, the 16 byte area beginning at tfcb + 16 10 is a l so 
initialized with the filename Y and filetype ZAP. It is the responsibility 
of the program to move this second filename and filetype to another area 
(usually a separate file control block) before opening the file, which 
begins at tbase, since the open operation will fill the disk map portion, 
thus overwriting the second name and type. 

If no file names were specified in the original command, then the 
fields beginning at tfcb and tfcb + 16 both contain blanks (20H). If 
one file name was specified, then the field at tfcb + 16 contains blanks. 
If the filetype is omitted, then the field is assumed to contain blanks. 

In all cases, the CCP translates lower case alphabetics to upper case 
to be consistent with the CP/M file naming conventions. 

As an added programming convenience, the default buffer at tbuff 
is initialized to hold the entire command line past the program name. 
Address tbuff contains the number of characters, and tbuff+1, tbuff +2, 

__ contain the remaining characters up to, but not including, the 

carriage return. Given that the above command has been typed at 
the console, the area beginning at tbuff is set up as follows: 

tbuf f: 

+0 +1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 

12J6X.ZOTtfY.ZAP??? 

where 12 is the number of valid characters (in binary), and tf represents 
an ASCII blank. Characters are given in ASCII upper case, with un¬ 
initialized memory following the last valid character. 

Again, it is the responsibility of the program to extract the infor¬ 
mation from this buffer before any file operations are performed since 
the FDOS uses the tbuff area to perform directory functions. 

In a standard CP/M system, the following values are assumed: 


boot: 

0000H 

bootstrap load (warm start) 

entry: 

0005H 

entry point to FDOS 

tfcb: 

005CH 

first default file control block 

tfcb+16 

006CH 

second file name 

tbuff 

0080H 

default buffer address 

tbase: 

01 00H 

base of transient area 
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Figure 2. File Control Block Format 

0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 . 27 28 29 30 31 32 



ET FN FT EX RC DM NR 


FIELD FCB POSITIONS 


PURPOSE 


0 Entry type (currently not used, 

but assumed zero) 


FN 

1-8 

File name, padded with ASCII 
blanks 

FT 

9-11 

File type, padded with ASCII 
blanks 

EX 

12 

File extent, normally set to 
zero 


13-14 

Not used, but assumed zero 

RC 

15 

Record count is current extent 
Size (0 to 128 records) 

DM 

16-31 

Disk allocation map, filled-in 
and used by CP/M 

NR 

32 

Next record number to read or 
write 
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3.3 Disk Access Primitives 

Given that a program has properly initialized the FCB's for 
each of its files, there are several operations which can be per 
formed, as shown in Table II. In each case, the operation is 
applied to the currently selected disk (see the disk select oper 
ation in Table II), using the file information in a specific FCB 
The following PL/M program segment, for example, copies the con¬ 
tents of the file X.Y to the (new) file NEW.FIL: 

DECLARE RET BYTE; 


OPEN: 

PROCEDURE (A) 

DECLARE A ADDRESS; 

RET=MON2(15,A); 

END OPEN; 

CLOSE: 

PROCEDURE (A) ; 

DECLARE A ADDRESS; 

RET=MON2(16,A); 

END; 

MAKE: 

PROCEDURE (A); 

DECLARE A ADDRESS; 

RET=MON2(22,A); 

END MAKE; 

DELETE: 

PROCEDURE (A); 

DECLARE A ADDRESS; 

/* IGNORE RETURNED VALUE */ 

CALL MON1(19,A); 

END DELETE; 

READBF: 

PROCEDURE (A); 

DECLARE A ADDRESS; 

RET=MON2(20,A); 

END READBF; 

WRITEBF: 

PROCEDURE (A); 

DECLARE A ADDRESS; 

RET=MON2(21,A); 

END WRITEBF; 

INIT: 

PROCEDURE; 

CALL MON1(13,0) ; 

END INIT; 


/* SET UP FILE CONTROL BLOCKS */ 

DECLARE FCBl (33) BYTE 

INITIAL (0,’X ',’Y ',0,0,0,0), 

FCB2 (33) BYTE 

INITIAL (0,'NEW ','FIL',0,0,0,0); 
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CALL INIT; 

/* ERASE ’NEW.FIL' IF IT EXISTS */ 

CALL DELETE (.FCB2); 

/* CREATE''NEW.FIL' AND CHECK SUCCESS */ 

CALL MAKE (. FCB2) ; 

IF RET = 255 THEN CALL PRINT (.'NO DIRECTORY SPACE $'); 
ELSE 

DO; /* FILE SUCCESSFULLY CREATED, NOW OPEN 'X.Y' */ 
CALL OPEN (.FCB1); 

IF RET = 255 THEN CALL PRINT (.'FILE NOT PRESENT $'); 
ELSE 

DO; /* FILE X.Y FOUND AND OPENED, SET 
NEXT RECORD TO ZERO FOR BOTH FILES */ 

FCB1(32), FCB2(32) = 0; 

/* READ FILE X.Y UNTIL EOF OR ERROR */ 

CALL READBF (.FCBl); /*READ TO 80H*/ 

DC WHILE RET = 0; 

CALL WRITEBF (.FCB2) /*WRITE FROM 80H*/ 

IF RET = 0 THEN /*GET ANOTHER RECORD*/ 

CALL READBF (.FCBl); ELSE 

CALL PRINT (. 'DISK WRITE ERROR $' ) ; 

END; 

IF RET < >1 THEN CALL PRINT (.' TRANSFER ERROR $'); 
ELSE 

DO; CALL CLOSE (.FCB2); 

IF RET = 255 THEN CALL PRINT (.'CLOSE ERROR$'); 
END; 

END; 

END; 

EOF 


This program consists of a number of utility procedures for 
opening, closing, creating, and deleting files, as well as two 
procedures for reading and writing data. These utility procedures 
are followed by two FCB’s for the input and output files. In 
both cases, the first 16 bytes are initialized to the < filename > 
and < filetype > of the input and output files. The main program 
first initializes the disk system, then deletes any existing 
copy of "NEW.FIL" before starting. The next step is to create 
a new directory entry (and empty file) for "NEW.FIL". If file 
creation is successful, the input file "X.Y" is opened. If this 
second operation is also successful, then the disk to disk copy 
can proceed. The NR fields are set to zero so that the first 
record of each file is accessed on subsequent disk I/O operations. 
The first call to READBF fills the (implied) DMA buffer at 80H 
with the first record from X.Y. The loop which follows copies 
the record at 80H to "NEW.FIL" and then reports any errors, or 
reads another 128 bytes from X.Y. This transfer operation con¬ 
tinues until either all data has been transferred, or an error 
condition arises. If an error occurs, it is reported; other¬ 
wise the new file is closed and the program halts. 
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Note^: The I/O operations transfer data to/from address 80H for the next 128 bytes unless 
the DMA address has been altered (see function 26) . Further, the NR field of the 
FCB is automatically incremented after the operation. If the NR field exceeds 128 
the next extent is opened automatical!^ and the NR field is reset to zero. 
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3.4 Random Access 

Recall that a single FCB describes up to a 16K segment of a 
(possibly) larger file. Random access within the first 16K seg¬ 
ment is accomplished by setting the NR field to the record number 
of the record to be accessed before the disk I/O takes place. 

Note, however, that if the 128th record is written, then the 
BDOS automatically increments the extent field (EX), and opens 
the next extent, if possible. In this case, the program must 
explicitly decrement the EX field and re-open the previous extent. 
If random access outside the first 16K segment is necessary, 
then the extent number e be explicitly computed, given an absol¬ 
ute record number r as 


or equivalently. 



e = SHR(r,7) 


this extent number is then placed in the EX field before the seg¬ 
ment is opened. The NR value n is then computed as 


n = r mod 128 


or 


n = r AND 7FH. 


When the programmer expects considerable cross-segment accesses, 
it may save time to create an FCB for each of the 16K segments, 
open all segments for access, and compute the relevant FCB from 
the absolute record number r. 


4. SYSTEM GENERATION 

As mentioned previously, every diskette used under CP/M is assumed to 
contain the entire system (excluding transient commands) on the first two 
tracks. The operating system need not be present, however, if the diskette 
is only used as secondary disk storage on drives B, C, ..., since the CP/M 
system is loaded only from drive A. 

The CP/M file system is organized so that an IBM-compatible diskette 
from the factory (or from a vendor which claims IBM compatibility) looks 
like a diskette with an empty directory. Thus, the user must first copy 
a version of the CP/M system from an existing diskette to the first two 
tracks of the new diskette, followed by a sequence of copy operations, 
using PIP, which transfer the transient command files from the original 
diskette to the new diskette. 
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NOTE: before you begin the CP/M copy operation, read your Licensing 

Agreement. It gives your exact legal obligations when making reproductions 
of CP/M in whole or in part, and specifically requires that you place the 
copyright notice 

Copyright (c), 1976 
Digital Research 

on each diskette which results from the copy operation. 

4.1. Initializing CP/M from an Existing Diskette 

The first two tracks are placed on a new diskette by running the tran¬ 
sient command SYSGEN, as described in the document "An Introduction to CP/M 
Features and Facilities." The SYSGEN operation brings the CP/M system from 
an initialized diskette into memory, and then takes the memory image and 
places it on the new diskette. 

Upon completion of the SYSGEN operation, place the original diskette 
on drive A, and the initialized diskette on drive B. Reboot the system; 
the response should be 

A> 

indicating that drive A is active. Log into drive B by typing 

B: 

and CP/M should respond with 

B> 

indicating that drive B is active. If the diskette in drive B is factory 
fresh, it will contain an empty directory. Non-standard diskettes may, 
however, appear as full directories to CP/M, which can be emptied by typing 

ERA 

when the diskette to be initialized is active. Do not give the ERA command 
if you wish to preserve files on the new diskette since all files will be 
erased with this command. 

After examining disk B, reboot the CP/M system and return to drive A for 
further operations. 

The transient commands are then copied from drive A to drive B using the 
PIP program. The sequence of commands shown below, for example, copy the 
principal programs from a standard CP/M diskette to the new diskette: 

A>PIPj 

*B:STAT.COM=STAT. COM; 

*B:PIP.COM=PIP.COMp 
*B : LOAD. COM=LOAD. COM^ 

*B:ED.COM=ED.COM^ 
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*B:ASM.COM=ASM.COM^ 

*B:SYSGEN.COM=SYSGEN.COM 
*B:DDT.COM=DDT.COMj J 

V 

A> 


The user should then log in disk B, and type the command 


DIR *.* 


j? 


to ensure that the files were transferred to drive B from drive A. The 
various programs can then be tested on drive B to check that they were 
transferred properly. 

Note that the copy operation can be simplified somewhat by creating 
a "submit" file which contains the copy commands. The file could be 
named GEN.SUB, for example, and might contain 


SYSGEN^ 

PIP B:STAT.COM=STAT.COM^ 

PIP B:PIP.COM=PIP.COM <? 

PIP B:LOAD.COM=LOAD.COM, 

PIP B:ED.COM=ED.COM y 
PIP B:ASM.COM=ASM.CO^ 

PIP B:SYSGEN.COM=SYSGEN.COM <? 
PIP B:DDT.COM=DDT.COM, 



The generation of a new diskette from the standard diskette is.then done 
by typing simply 


SUBMIT GEN 


5. CP/M ENTRY POINT SUMMARY 

The functions shown below summarize the functions of the 
FDOS. The function number is passed in Register C (first para¬ 
meter in PL/M), and the information is passed in Registers D,E 
(second PL/M parameter). Single byte results are returned in 
Register A. If a double byte result is returned, then the high- 
order byte comes back in Register B (normal PL/M return). The 
transient program enters the FDOS through location "entry" (see 
Section 7.) as shown in Section 2. for PL/M, or 


CALL entry 


in assembly language. All registers are altered in the FDOS. 
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Function 


Number 


Information 


0 

1 

2 

3 

4 

5 

6 

7 

8 
9 

10 

11 


System Reset 
Read Console 

Write Console ASCII character 

Read Reader 

Write Punch ASCII character 

Write List ASCII character 

(not used) 

Interrogate I/O Status 

Alter I/O Status I/O Status Byte 

Print Console Buffer Buffer Address 

Read Console Buffer Buffer Address 

Check Console Status 


12 

Life Disk Head 

13 

Reset Disk System 

14 

Select Disk 

15 

Open File 

16 

Close File 

17 

Search First 

18 

Search Next 

19 

Delete File 

20 

Read Record 

21 

Write Record 

22 

Create File 

23 

Rename File 

24 

Interrogate Login 

25 

Interrogate Disk 


Disk number 
FCB Address 


26 Set DMA Address DMA Address 

27 Interrogate Allocation 


Result 

ASCII character 

ASCII character 

I/O Status 6yte 


True if character 
Ready 


Completion Code 


Login Vector 

Selected Disk 
Number 

Address of Allo¬ 
cation Vector 
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6. ADDRESS ASSIGNMENTS 


The standard distribution version of CP/M is organized for an Intel 
MDS microcomputer developmental system with 16K of main memory, and two 
diskette drives. Larger systems are available in 16K increments, providing 
management of 32K, 48K, and 64K systems (the largest MDS system is 62K 
since the POM monitor provided with the MDS resides in the top 2K of the 
memory space). For each additional 16K increment, add 4000H to the values 

of cbase and fbase. 


The address assignments are 


boot = 0000H 
tfcb = 005CH 
tbuff= 0080H 
tbase= 0100H 
cbase= 2900H 
fbase= 3200H 
entry= 0005H 


warm start operation 

default file control block location 

default buffer location 

base of transient program area 

base of console command processor 

base of disk operating system 

entry point to disk system from 

user programs 
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7. SAMPLE PROGRAMS 


This section contains two sample programs which interface with the CP/M 
operating system. The first program is written in assembly language, and 
is the source program for the DUMP utility. The second program is the CP/M 
LOAD utility, written in PL/M. 


The assembly language program begins with a number of "equates" for sys 
tem entry points and program constants. The equate 

BDOS EQU 0005H 

for example, gives the CP/M entry point for peripheral I/O functions. The 
defualt file control block address is also defined (FCB), along with the 
default buffer address (BUFF). Note that the program is set up to run at 
locatiQn 100H, which is the base of the transient program area. The stack 
is first set-up by saving the entry stack pointer into OLDSP, and resetting 
SP to the local stack. The stack pointer upon entry belongs to the console 
command processor, and need not be saved unless control is to return to the 
CCP upon exit. That is, if the program terminates with a reboot (branch to 
location 0000H) then the entry stack pointer need not be saved. 

The program then jumps to MAIN, past a number of subroutines which are 
listed below: 

BREAK - when called, checks to see if there is a console 

character ready. BREAK is used to stop the listing 
at the console 

PCHAR - print the character which is in register A at the 
console. 

CRLF — send carriage return and line feed to the console 

PNIB - print the hexadecimal value in register A in ASCII 
at the console 

PHEX - print the byte value (two ASCII characters) in 
register A at the console 

- print error flag #n at the console, where n is 

1 if file cannot be opened 

2 if disk read error occurred 

- get next byte of data from the input file. If the 
IBP (input buffer pointer) exceeds the size of the 
input buffer, then another disk record of 128 bytes 
is read. Otherwise, the next character in the buffer 
is returned. IBP is updated to point to the next 
character. 


GNB 
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The MAIN program then appears, which begins by calling SETUP. The SETUP 
subroutine, discussed below, opens the input file and checks for errors. 

If the file is opened properly, the GLOOP (get loop) label gets control. 

On each successive pass through the GLOOP label, the next data byte 
is fetched using GNB and save in register B. The line addresses are listed 
every sixteen bytes, so there must be a check to see if the least signi— 
ficant 4 bits is zero on each output. If so, the line address is taken 
from registers h and 1, and typed at the left of the line. In all cases, 
the byte which was previously saved in register B is brought back to 

register A, following label NONUM, and printed in the output line. The 

cycle through GLOOP continues until an end of file condition is detected 
in DISKR, as described below. Thus, the output lines appear as 

0000 bb bb bb bb bb bb bb bb bb bb bb bb bb bb bb bb 

0010 bb bb bb bb bb bb bb bb bb bb bb bb bb bb bb bb 


until the end of file. 

The label FINIS gets control upon end of file. CKLF is called first 
to return the carriage from the last line output. The CCP stack pointer 
is then reclaimed from OLDSP, followed by a RET to return to the console 
command processor. Note that a JMP 0000H could be used following the 
FINIS label, which would cause the CP/M system to be brought in again from 
the diskette (this operation is necessary only if the CCP has been over¬ 
lay ed by data areas). 

The file control block format is then listed (FCBDN ... FCBLN) which 
overlays the fcb at location 05CH which is setup by the CCP when the 
DUMP program is initiated. That is, if the user types 

DUMP X.Y 

then the CCP sets up a properly formed fcb at location 05CH for the DUMP 
(or any other) program when it goes into execution. Thus, the SETUP sub¬ 
routine simply addresses this default fcb, and calls the disk system to 
open it. The DISKR (disk read) routine is called whenever GNB needs another 
buffer full of data. The default buffer at location 80H is used, along 
with a pointer (IBP) which counts bytes as they are processed. Normally, 
an end of file condition is taken as either an ASCII 1AH (control-z), or 
an end of file detection by the DOS. The file dump program, however, stops 
only on a DOS end of file. 







FILE DUMP PROGRAM, READS AN INPUT FILE AND PRINTS IN 
COPYRIGHT (C), DIGITAL RESEARCH, 1975, 1976 
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0100 



ORG 

100H 


0005 

= 

BDOS 

EQU 

0005H 

;DOS ENTRY POINT 

000F 

= 

OPENF 

EOU 

15 

;FILE OPEN 

0014 

= 

READF 

EOU 

20 

;READ FUNCTION 

0002 

= 

TYPEF 

EQU 

2 

;TYPE FUNCTION 

0001 

= 

CONS 

EQU 

1 

;READ CONSOLE 

000B 


BRKF 

EOU 

11 

;BREAK KEY FUNCTION (TRUE IF 

005C 

= 

FCB 

EOU 

5CH 

;FILE CONTROL BLOCK ADDRESS 

0080 


BUFF 

' 

EOU 

80H 

; INPUT DISK BUFFER ADDRESS 



• 

SET UP 

STACK 


0100 

210000 


LX I 

H , 0 


0103 

39 


DAD 

SP 


0104 

220F01 


SHLD 

OLDSP 


0107 

315101 


LX I 

SP,STKTOP 

010A 

C3C401 


JMP 

MAIN 




* 

VARIABLES 


01 0 D 


IBP: 

* 

DS 

2 

; INPUT BUFFER POINTER 



• 

STACK AREA 


010F 


OLDSP: 

DS 

2 


0111 


STACK: 

DS 

64 


0151 

= 

STKTOP 

EQU 

$ 




r 

• 

SUBROUTINES 




BREAK: 

;CHECK 

BKEAK key 

(ACTUALLY ANY KEY WILL DO) 

0151 

E5D5C5 


PUSH H! 

PUSH D! 

PUSH B; ENVIRONMENT SAVED 

0154 

0E0B 


MV I 

C,BRKF 


0156 

CD0500 


CALL 

BDOS 


0159 

C1D1E1 


POP B! 

POP D! POP H; ENVIRONMENT RESTORED 

015C 

C9 


RET 





PCHAR: 

;PRINT 

A CHARACTER 

015D 

E5D5C5 


PUSH H! 

PUSH D! 

PUSH B; SAVED 

0160 

0E02 


MVI 

C,TYPEF 


0162 

5F 


MOV 

E,A 


0163 

CD0500 


CALL 

BDOS 


0166 

C1D1E1 


POP B! 

POP D! POP H: RESTORED 

0169 

C9 


RET 





CRLF: 




016A 

3E0D 


MVI 

A, 0DH . 


016C 

CD5D01 


CALL 

PCHAR 


016F 

3E0A 


MVI 

A, 0AH 


0171 

CD5D01 


CALL 

PCHAR 


0174 

C9 

9 

RET 





• 

PNIB: 

;PRINT 

NIBBLE IN 

REG A 

0175 

E60F 


AN I 

0FH 

;LOW 4 BITS 

0177 

FE0A 


CPI 

10 


0179 

D28101 


JNC 

Pi 0 



CHAR READY) 












017C C630 
017E C38301 


0181 C637 
0183 CD5D01 
0186 C9 


0187 F5 
0188 0F 
0189 0F 
018A 0F 
0188 0F 
018C CD7501 
018F FI 
0190 CD7501 
0193 C9 


0194 CD6A01 
0197 3E23 
0199 CD5D01 
019C 78 
019D C630 
019F CD5D01 
01A2 CD6A01 
01A5 C3F701 


01A8 3A0D01 
01AB FE80 
01AD C2B401 


0180 CD1602 
01B3 AF 


01B4 5F 
01B5 160(3 
0187 3C 
0188 320D01 


01BB E5 
01BC 218000 
01BF 19 
01C0 7E 


01C1 El 
01C2 23 
01C3 C9 


LESS THAN OR EQUAL TO 9 
ADI '0' 

JMP PRN 


; GREATER OR EQUAL TO 10 

P10: ADI 'A' - 10 

PRN: CALL PCHAR 

RET 


PHEX: ;PRINT HEX CHAR IN REG A 


PUSH 

RRC 

RRC 

RRC 

RRC 

CALL 

POP 

CALL 

RET 


PSW 


PNIB 

PSW 

PNIB 


; PRINT NIBBLE 


J5RR: ; PRINT ERROR MESSAGE 


GNB; 


CALL 

CRLF 

MV I 

A, '# ' 

CALL 

PCHAR 

MOV 

A, B 

ADI 

'0' 

CALL 

PCHAR 

CALL 

CRLF 

JMP 

FINIS 

;GET 

NEXT BYTE 

LDA 

IBP 

CPI 

80H 

JNZ 

G0 

READ 

ANOTHER B' 

CALL 

DISKR 

XRA 

A 


• 

G0: ;READ THE BYTE AT BUFF+REG A 

MOV E,A 

MVI D t 0 

INR A 

STA IBP 

; POINTER IS INCREMENTED 

; SAVE THE CURRENT FILE ADDRESS 

PUSH H 

LX I H,BUFF 

DAD D 

MOV A, M 

. BYTE IS IN THE ACCUMULATOR 

! RESTORE FILE ADDRESS AND INCREMENT 

POP H 

INX H 

RET 
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01C4 CDFF01 


MAIN: 


; READ AND PRINT SUCCESSIVE BUFFERS 
CALL SETUP ;SET UP INPUT FILE 







01C7 

01C9 

01CC 

3E8 0 

320D01 

21FFFF 

% 

MVI 

3TA 

LX I 

A, 80H 

IBP ;SET BUFFER POINTER TO 80H 

H,0FFFFH ;SET TO -1 TO START 

01CF 

01D2 

CDA801 

47 

9 

GLOOP: 

CALL 

MOV 

GNB 

B, A 



• 

9 

PRINT 

HEX VALUES 
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01D3 


* 

CHECK 

FOR LINE 

FOLD 


7D 


MOV 

A, L 


01D4 

E60F 


AN I 

0FH 

; CHECK 

LOW 4 BITS 

01D6 

C2EB01 


JNZ 

NONUM 

01D9 


f 

PR INI- 

LINE NUMBER 


CD6A01 

• 

CALL 

CRLF 



01 DC 


f 

? 

CHECK 

FOR BREAK KEY 


CD5101 


CALL 

BREAK 



01DF 

0F 


RRC 



01E0 

DA F 7 01 


JC 

FINIS 

; DON'T 

PRINT ANY MORE 

01E3 

7C 

/ 

MOV 

A, H 



01E4 

CD8701 


CALL 

PHEX 



01E7 

7D 


MOV 

A, L 



01E8 

CD8701 

NONUM: 

CALL 

PHEX 



01EB 

3E20 


MVI 

A, ' ' 



01 ED 

CD5D01 


CALL 

PCHAR 



01F0 

78 


MOV 

A, B 



01F1 

CD8701 


CALL 

PHEX 



01F4 

C3CF01 


JMP 

GLOOP 





EPSA: 

; END PSA 






? 

END OF 

INPUT 




FINIS: 





01F7 

CD6A01 


CALL 

CRLF 



01 FA 

2A0F01 


LHLD 

OLDSP 



01FD 

F9 


SPHL 




01FE 

C9 


RET 





005C 

005D 

0065 

0068 

006B 

007C 

007D 


CONTROL BLOCK DEFINITIONS 


FILE 

FCBDN EQU FCB+0 ;DISK NAME 

FCBFN EQU FC8+1 ;FILE NAME 

FCBFT EQU FCB+9 ;DISK FILE TYPE (3 CHARACTERS) 

FCBRL EQU FCB+12 ;FILE'S CURRENT REEL NUMBER 

FCBRC EQU FCB+15 ;FILE'S RECORD COUNT (0 TO 128) 

FCBCR ECU FCB+32 ;CURRENT (NEXT) RECORD NUMBER ( 

FCBLN EQU FCB+33 ;FCB LENGTH 


0 TO 12 7) 


01FF 115C00 
0202 0E0F 
0204 CD0500 

0207 FEFF 
0209 C21102 


t 

SETUP: ;SET UP FILE 
; OPEN THE FILE FOR INPUT 

LX I D, FCB 

MVI C,OPENF 

CALL BDOS 

,* CHECK FOR ERRORS 

CPI 255 

JNZ OPNOK 











; BAD OPEN 


020C 

0601 

MV I 

B > 1 

;OPEN 1 

020E 

CD9401 

CALL 

ERR 




OPNOK : ;OPEN 

IS OK. 


0211 

AF 

XRA 

A 


0212 

327C00 

STA 

FCBCR 


0215 

C9 

RET 





DISKR: ;READ 

DISK FILE 

RECORD 

0216 

E5D5C5 

PUSH H! PUSH D! 

PUSH B 

0219 

115C00 

LX I 

D,FC6 


021C 

0E14 

MV I 

C,READF 


021E 

CD0500 

CALL 

BDOS 


0221 

C1D1E1 

POP B! 

POP D! POP H 

0224 

FE00 

CPI 

0 

;ChECK 

0226 

C8 

RZ 





; MAX BE 

EOF 


0227 

FE01 

CPI 

1 


0229 

CAF701 

JZ 

FINIS 


022C 

0602 

MV I 

B,2 

;DISK 

022E 

CD9401 

CALL 

ERR 


0231 


END 
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The PL/M program which follows implements the CP/M LOAD utility. The 
function is as follows. The user types 


LOAD filename 


; 


If filename.HEX exists on the diskette, then the LOAD utility reads the "hex" 
formatted machine code file and produces the file 


filename.COM 

where the COM file contains an absolute memory image of the machine code, 
ready for load and execution in the TPA. If the file does not appear on 
the diskette, the LOAD program types 


SOURCE IS READER 


and reads an Addmaster paper tape reader which contains the hex file. 

The LOAD program is set up to load and run in the TPA, and, upon com¬ 
pletion, return to the CCP without rebooting the system. Thus, the pro¬ 
gram is constructed as a single procedure called LOADCOM which takes the 
form 


r 


OFAH: 

LOADCOM: PROCEDURE; 

/* LIBRARY PROCEDURES */ 

M0N1: ... 

/* END LIBRARY PROCEDURES */ 

MOVE: ... 

GETCHAR: ... 

PRINTNIB: ... 

PRINTHEX: ... 

PRINTADDR: .. . 

RELOC: ... 

SETMEM: 

READHEX: 

READBYTE: 

READCS: 

MAKEDOUBLE: 

DIAGNOSE: 

'“END RELOC; 

DECLARE STACK(16) ADDRESS, SP ADDRESS; 

SP = STACKPTR; STACKPTR = .STACK(LENGTH(STACK)); 


< 


CALL RELOC? 

\ STACKPTR = SP; 
V RETURN 0; 

END LOADCOM; 


EOF 
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The label OFAH at the beginning sets the origin of the compilation to OFAli, 
which causes the first 6 bytes of the compilation to be ignored when loaded 
(i.e., the TPA starts at location 100H and thus OFAH,,OFFH are deleted 
from the COM file). In a PL/M compilation, these 6 bytes are used to set up 
the stack pointer and branch around the subroutines in the program. In this 
case, there is only one subroutine, called LOADCOM, which results in the 
following machine memory image for LOAD 

OFAH: LXI SP,plmstack ;SET SP TO DEFAULT STACK 

OFDH: JMP pastsubr ;JUMP AROUND LOADCOM 

100H: beginning of LOADCOM procedure 

end of LOADCOM procedure 
RET 

pastsubr: 

El 

HLT 

Since the machine code between OFAH and OFFH is deleted in tiie load, 
execution actually begins at the top of LOADCOM. Note, however, that 
the initialization of the SP to the default stack has also been deleted; 
thus, there is a declaration and initialization of an explicit stack and 
stack pointer before the call to RELOC at the end of LOADCOM. This is 
necessary only if we wish to return to the CCP without a reboot operation: 
otherwise the origin of the program is set to 100H, the declaration of 
LOADCOM as a procedure is not necessary, and termination is accomplished 
by simply executing a 

GO TO 0000H; 

at the end of the program. Note also that the overhead for a system re¬ 
boot is not great (approximately 2 seconds), but can be bothersome for 
system utilities which are used quite often, and do not need the extra 
space. 

The procedures listed in LOADCOM as "library procedures" are a standard 
set of PL/M subroutines which are useful for CP/M interface. The RELOC 
procedure contains several nested subroutines for local functions, and 
actually performs the load operation when called from LOADCOM. Control 
initially starts on line 327 where the stackpointer is saved and re-initialized 
to the local stack. The default file control block name is copied to 
another file control block (SFCB) since two files may be open at the same 
time. The program then calls SEARCH to see if the HEX file exists; it not, 
then the high speed reader is used. If the file does exist, it is opened or 
input (if possible). The filetype COM is moved to the default file control 
block area, and any existing copies of filename.COM files are removed from 
the diskette before creating a new file. The MAKE operation creates a new 
file, and, j.f successful, RELOC is called to read the HEX file and produce 
the COM file. At the end of processing by RELOC, the COM file is closed 
(line 350) . Note that the HEX file does not need to be closed since it 
was opened for input only. The dtta written to a file is not permanently 
recorded until the file is successfully closed. 








3t 


Di s k input characters are read through the procedure GETCHAR on line 
137. Although the DMA facilities of CP/M could be used here, the GETCHAR 
procedure instead uses the default buffer at location 80H and moves each 
buffer into a vector called SBUFF (source buffer) as it is read. On exit 
the GETCHAR procedure returns the next input character and updates the 
source buffer pointer (SBP). 

SETMEM Procedure on line 191 performs the opposite function from 
GETCHAR. The SETMEM procedure maintains a buffer of loaded machine code 
in pure binary form which acts as a "window" on the loaded code. If there 

fj! a ! t !" iPt by . REL0C to write below this window, then the data is ignored. 

6 data 1S Wlthin the window, then it is placed into MBUFF (memory 
buffer). If the data is to be placed above this window, then the window 
is moved up to the point where it would include the data address by writing 
the memory image successively (by 128 byte buffers), and moving the base 
address of the window. Using this technique, the programmer can recover 
rom checksum errors on the high-speed reader by stopping the reader, 

1:116 tap6 f ° r SCme distance ' th en restarting LOAD (in this case, 
LOADing is resumed by interrupting with a NOP instruction). Again, the 
SETMEM procedure uses the default buffer at location 80H to perform the 

disk output by moving 128 byte segments to 80H through OFFH before each 
write. 
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00001 
00002 
00003 
00004 
00005 
00006 
00007 
00008 
00009 
00010 
00011 
00012 
00013 
ESS */ 
00014 
00015 
00016 


/ 

00017 

00018 

00019 

00020 

00021 

00022 

V 

00023 

00024 


1 

1 

1 

1 

1 

1 

1 

1 

1 

2 

2 

2 

2 

2 

2 

2 

2 

2 

2 

2 

2 

2 

2 

2 


ROM THE 
00025 2 

S THE MACH 
00026 2 


0FAH: DECLARE BDOS LITERALLY '0005H'; 
/* TRANSIENT COMMAND LOADER PROGRAM 


V 


COPYRIGHT (C) DIGITAL RESEARCH 
JUNE, 1975 


LOADCOM: PROCEDURE BYTE; 

DECLARE FCBA ADDRESS INITIAL(5CH) ; 

DECLARE FCB BASED FCBA (33) BYTE; 

DECLARE BUFFA ADDRESS INITIAL( 80H), /* I/O BUFFER ADDR 

BUFFER BASED BUFFA (128) BYTE; 

DECLARE SFCB(33) BYTE, /* SOURCE FILE CONTROL BLOCK * 

BSIZE LITERALLY '1024', 

EOFILE LITERALLY '1AH', 

SBUFF(BSIZE) BYTE /* SOURCE FILE BUFFER */ 

INITIAL(EOFILE), 

RFLAG BYTE, ' /* READER FLAG */ 

SBP ADDRESS; /* SOURCE FILE BUFFER POINTER 


/* LOADCOM LOADS TRANSIENT COMMAND FILES TO THE DISK F 
CURRENTLY DEFINED READER PERIPHERAL. THE LOADER PLACE 
CODE INTO A FILE WHICH APPEARS IN THE LOADCOM COMMAND 


00027 

2 

/* **************** library 

PROCEDURES 

****** 

V 



00028 

2 



00029 

2 

MONl; PROCEDURE(F,A); 


00030 

3 

DECLARE F BYTE, 


00031 

3 

A ADDRESS; 


00032 

3 

GO TO BDOS; 


00033 

3 

END MONl; 


00034 

2 



00035 

2 

MON2: PROCEDURE(F,A) BYTE; 


00036 

3 

DECLARE F BYTE, 


00037 

3 

A ADDRESS; 


00038 

3 

GO TO BDOS; 


00039 

3 

END MON2; 


00040 

2 



00041 

2 

READRDR; PROCEDURE BYTE; 


00042 

3 

/* READ CURRENT READER DEVICE */ 

00043 

3 

RETURN MON2(3,0) ; 


00044 

3 

END READRDR; 


00045 

2 



00046 

2 

DECLARE 


00047 

2 

TRUE LITERALLY '1', 


00048 

2 

FALSE LITERALLY '0', 


00049 

2 

FOREVER LITERALLY 'WHILE 

TRUE', 

000 50 

2 

CR LITERALLY '13', 









00051 2 

00052 2 

00053 2 

00054 2 

00055 3 

00056 3 

00057 3 

00058 2 

00059 2 

00060 3 

00061 3 

00062 3 

00063 2 

00064 2 

00065 3 

00066 3 

00067 3 

00068 3 
00069 3 

00070 3 

00071 2 

00072 2 

00073 2 

00074 2 

00075 3 

00076 3 

00077 2 

00078 2 

00079 3 

00080 3 

00381 3 

00082 2 
00083 2 

00084 3 

00085 3 

00086 3 

00087 2 

00088 2 
00-089 3 

00090 3 

00091 3 

00092 2 

00093 2 

00094 3 

00095 3 

00096 3 

00097 2 

00098 2 

00099 3 

00100 3 
00101 2 
00102 2 
00103 3 

00104 3 

00105 3 

00106 2 
00107 2 

00108 3 

00109 3 

00110 3 


LF LITERALLY '10', 

WHAT LITERALLY '63'; 

PRINTCHAR: PROCEDURE(CHAR); 

DECLARE CHAR BYTE; 

CALL MON1(2,CHAR); 

END PRINTCHAR; 

CRLF: PROCEDURE; 

CALL PRINTCHAR(CR); 

CALL PRINTCHAR(LF); 

END CRLF; 

PRINT: PROCEDURE(A) ; 

DECLARE A ADDRESS; 

/* PRINT THE STRING STARTING AT ADDRESS 
NEXT DOLLAR SIGN IS ENCOUNTERED */ 

CALL CRLF; 

CALL MON1(9,A) ; 

END PRINT; 

DECLARE DCNT BYTE; 

INITIALIZE: PROCEDURE; 

CALL MON1(13,0); 

END INITIALIZE; 

SELECT: PROCEDURE(D); 

DECLARE D BYTE; 

CALL MON1(14,D) ; 

END SELECT; 

OPEN: PROCEDURE(FCB); 

DECLARE FCB ADDRESS; 

DCNT = MON2(15,FCB); 

END OPEN; 

CLOSE: PROCEDURE(FCB); 

DECLARE FCB ADDRESS; 

DCNT = MON2(16,FCB); 

END CLOSE; 

SEARCH: PROCEDURE(FCB); 

DECLARE FCB ADDRESS; 

DCNT = MON2(17,FCB); 

END SEARCH; 

SEARCHN: PROCEDURE; 

DCNT = MON2(18,0); 

END SEARCHN; 

DELETE: PROCEDURE(FCB); 

DECLARE FCB ADDRESS; 

CALL MON1(19,FCB); 

END DELETE; 

DISKREAD: PROCEDURE(FCB) BYTE; 

DECLARE FCB ADDRESS; 

RETURN MON2(20,FCB); 

END DISKREAD; 


33 


UNTIL THE 









00111 2 
00112 2 
00113 3 

00114 3 

00115 3 

00116 2 
00117 2 

00118 3 

00119 3 

00120 3 

00121 2 
00122 2 
00123 3 

00124 3 

00125 3 

00126 2 
00127 2 

* * * * ★ */ 
00128 2 
00129 2 

00130 3 

00131 3 

00132 3 

00133 3 

00134 4 

00135 3 

00136 2 

00137 2 

00138 3 

00139 3 

00140 3 

00141 3 

00142 3 

00143 3 

00144 3 

00145 3 

00146 4 

00147 4 

ROR$'); 
00148 5 

00149 5 

00150 5 

00151 4 

00152 3 

00153 3 

00154 2 

00155 2 

00156 2 

00157 2 

00158 2 

00159 3 

00160 3 

00161 3 

00162 3 

00163 2 

00164 2 

00165 3 

00166 3 

00167 3 

00168 2 


DISKWRITE: PROCEDURE(FCB) BYTE; 

DECLARE FCB ADDRESS; 

RETURN MON2 (21 , FCB) ; 

END DISKWRITE; 

MAKE: PROCEDURE(FCB); 

DECLARE FCB ADDRESS; 

DCNT = MON2(22,FCB) ; 

END MAKE; 

RENAME: PROCEDURE(FCB) ; 

DECLARE FCB ADDRESS; 

CALL MON1(23,FCB) ; 

END RENAME; 

/* ******************* end OF LIBRARY PROCEDURES ******** 


MOVE: PROCEDURE(S,D,N); 

DECLARE (S,D) ADDRESS, N BYTE, 

A BASED S BYTE, 8 BASED D BYTE; 

DO WHILE (N:=N-1) <> 255; 

B = A; S=S+1; D=D+1; 

END; 

END MOVE; 

GETCHAR: PROCEDURE BYTE; 

/* GET NEXT CHARACTER */ 

DECLARE I BYTE; 

IF RFLAG THEN RETURN READRDR; 

IF (SBP := SBP+1) <= LAST(SBUFF) THEN 

RETURN SBUFF(SBP); 

/* OTHERWISE READ ANOTHER BUFFER FULL */ 

DO SBP = 0 TO LAST(SBUFF) BY 128; 

IF (I:=DISKREAD(,SFCB)) = 0 THEN 

CALL MOVE (80H,.SBUFF(SBP),80H); ELSE 

DO; IF IOl THEN CALL PRINT (.'DISK READ ER 

SBUFF(SBP) = EOFILE; 

SBP = LAST(SBUFF); 

END; 

END; 

SBP = 0; RETURN SBUFF; 

END GETCHAR; 

DECLARE 

3TACKPOINTER LITERALLY STACKPTR ; 


PRINTNIB: PROCEDURE(N); 

DECLARE N BYTE; 

IF N > 9 THEN CALL PRINTCHAR(N+ A -10); 
CALL PRINTCHAR(N+'0 ') » 

END PRINTNIB; 


ELSE 


PRINTHEX: PROCEDURE(B); 

DECLARE 6 BYTE; 

CALL PRINTNIB(SHR(B,4)) 
END PRINTHEX; 


CALL PRINTNIB(B AND 0FH); 







00169 2 

00170 3 

00171 3 

00172 3 

00173 2 

00174 2 

00175 2 

00176 2 

00177 2 

00178 3 

00179 3 

00180 3 

00181 3 

00182 3 
00183 3 

00184 3 

00185 3 

OC */ 
00186 3 

00187 3 

00188 3 

00189 3 

00190 3 

00191 3 

00192 4 

*/ 

00193 4 

00194 4 

00195 4 

GRAPH */ 
00196 4 

00197 5 

00198 6 

00199 5 

00200 5 

00201 5 

00202 5 

00203 6 

00204 6 

00205 6 

00206 6 
00207 5 

00208 4 

00209 4 

00210 3 

00211 3 

00212 4 

00213 4 

00214 4 

00215 4 

00216 4 

00217 4 

00218 3 

00219 3 

00220 4 

00221 4 

00222 4 

00223 3 

00224 3 

00225 4 


PRINTADDR: PROCEDURE(A); 

DECLARE A ADDRESS; 

CALL PRINTHEX(HIGH(A) ) ; CALL PRINTHEX(LOW(A)) ; 

END PRINTADDR; 

35 

/* INTEL hEX FORMAT LOADER */ 


RELOC: PROCEDURE; 

DECLARE (RL, CS, 
DECLARE 

LA ADDRESS, 
TA ADDRESS, 
SA ADDRESS, 
FA ADDRESS, 
NB ADDRESS, 
SP ADDRESS, 


RT) BYTE; 

/* LOAD ADDRESS */ 

/* TEMP ADDRESS */ 

/* START ADDRESS */ 

/* FINAL ADDRESS */ 

/* NUMBER OF BYTES LOADED */ 

/* STACK POINTER UPON ENTRY TO REL 


MBUFF(256) BYTE, 
P BYTE, 

L ADDRESS; 


SETMEM: PROCEDURE(B); 

/* SET MBUFF TO B AT LOCATION LA MOD LENGTH(MBUFF) 
DECLARE (B,I) BYTE; 

IF LA < L THEN /* MAY BE A RETRY */ RETURN; 

DO WHILE LA > L + LAST(MBUFF); /* WRITE A PARA 


DO I = 0 TO 127; /* COPY INTO BUFFER 
BUFFER(I) = MBUFF(LOW(L)); L = L + 1; 
END; 

/* WRITE BUFFER ONTO DISK */ 

P = P + 1; 

IF DISKWRITE(FCBA) <> 0 THEN 

DO; CALL PRINT(.'DISK WRITE ERRORS'); 
HALT; 

/* RETRY AFTER INTERRUPT NOP */ 

L * L - 128; 

END; 


END; 

MBUFF(LOW(LA)) = 6; 

END SETMEM; 


V 


READHEX: PROCEDURE BYTE; 

/* READ ONE HEX CHARACTER FROM THE INPUT */ 
DECLARE H BYTE; 

IF (H := GETCHAR) - '0' <= 9 THEN RETURN H - '0'- 

IF H - A' > 5 THEN GO TO CHARERR; 

RETURN H - 'A' + 10; 

END READHEX; 

READBYTE: PROCEDURE BYTE; 

/* READ TWO HEX DIGITS */ 

RETURN 3HL(READHEX,4) OR READHEX; 

END READBYTE; 


READCS: PROCEDURE BYTE; 

/* READ BYTE WHILE COMPUTING CHECKSUM */ 










00226 4 

00227 4 

00228 4 

00229 4 

00230 3 

00231 3 

00232 4 

S V 

00233 4 

00234 4 

00235 4 

00236 3 

00237 3 

00238 4 

00239 4 

00240 4 

00241 4 

00242 5 


DECLARE B BYTE; 

CS = CS + (B ;= READBYTE) ; 

RETURN B; 

END READCS; 36 

MAKE$DOUBLE: PROCEDURE(H,L) ADDRESS; 

/* CREATE A BOUBLE BYTE VALUE FROM TWO SINGLE BYTE 

DECLARE (H,L) BYTE; 

RETURN SHL(DOUBLE(H),8) OR L; 

END MAKESDOUBLE; 

DIAGNOSE: PROCEDURE; 

DECLARE M BASED TA BYTE; 

NEWLINE: PROCEDURE; 

CALL CRLF; CALL PRINTADDR(TA); CALL PRINTCHAR( : t 


00243 5 

00244 5 

00245 4 

00246 4 

00247 4 

00248 4 

00249 4 

00250 4 

00251 4 

00252 4 

00253 5 

00254 5 

00255 5 

00256 4 

00257 4 

00258 4 

00259 3 

00260 3 

00261 3 

00262 3 

00263 3 

00264 3 

00265 3 

V 

00266 3 

00267 3 

NTERED V 
00268 3 

00269 4 


CALL PRINTCHAR(' '); 

END NEWLINE; 

/* PRINT DIAGNOSTIC INFORMATION AT THE CONSOLE */ 

CALL PRINT(.* LOAD ADDRESS $'); CALL PRINTADDR(TA) 
CALL PRINT(.'ERROR ADDRESS $'); CALL PRINTADDR(LA) 

CALL PRINT (.'BYTES READ:$'); CALL NEWLINE; 

DO WHILE TA < LA? 

IF (LOW(TA) AND 0FH) = 0 THEN CALL NEWLINE; 

CALL PRINTHEX(MBUFF(TA-L)); TA=TA+1; 

CALL PRINTCHAR(' '); 

END; 

CALL CRLF; 

HALT • 

END DIAGNOSE; 


/* INITIALIZE */ 

SA, FA, NB = 0; 

SP = STACKPOINTER; 
p = 0; /* PARAGRAPH COUNT V 

TA,LA,L = 100H; /* BASE ADDRESS OF TRANSIENT ROUTINES 

IF FALSE THEN „ 

CHARERR: /* ARRIVE HERE IF NON-HEX DIGIT IS ENCCL 

DO; /* RESTORE STACKPOINTER V STACKPOINTER = SP; 
CALL PRINT(.'NON-HEXADECIMAL DIGIT ENCOUNTERED S ) 


00270 4 

00271 4 

00272 3 

00273 3 

00274 3 

00275 3 

00276 3 

00277 3 

00278 3 

00279 4 


CALL DIAGNOSE; 
END; 


/* READ RECORDS UNTIL :00XXXX IS ENCOUNTERED V 

DO FOREVER; 

/* SCAN THE : V 

DO WHILE GETCHAR <> ':'; 

END; 









4 

4 

4 

4 

4 

4 

4 

4 

4 

4 

4 

4 

4 

4 

4 

4 

4 

4 

5 

4 

4 

4 

4 

4 

5 

5 

4 

3 

3 

3 

3 

3 

3 

4 

3 

3 

3 

3 

3 

3 

3 

3 

2 

2 

E 

2 

2 

2 

2 

2 


/* SET CHECK SUM TO ZERO, AND SAVE THE RECORD LENG 


CS = 0; 

/* MAY BE THE END OF TAPE */ 

IF (RL := READCS) = 0 THEN 
GO TO FIN; 

NB = NB + PL; 

TA, LA = MAKESDGUBLE(READCS,READCS); 
IF SA = 0 THEN SA = LA; 


/* READ THE RECORD TYPE (NOT CURRENTLY USED) */ 
RT = READCS; 

/* PROCESS EACH BYTE */ 

DO WHILE (RL := RL - 1) <> 255; 

CALL SETMEM(READCS); LA = LA+1; 

END; 

IF LA > FA THEN FA = LA - 1; 

/* NOW READ CHECKSUM AND COMPARE */ 

IF CS + READBYTE <> 0 THEN 

DO; CALL PRINT(.'CHECK SUM ERROR $'); 

CALL DIAGNOSE; 

END; 

END; 


FIN: 

/* EMPTY THE BUFFERS */ 

TA = LA; 

DO WHILE L < TA; 

CALL SETMEM(0); LA = LA+1; 

END; 

/* PRINT FINAL STATISTICS */ 

CALL PRINT(.'FIRST ADDRESS $'); CALL PRINTADDR(SA); 

CALL PRINT(. LAST ADDRESS $'); CALL PRINTADDR(FA); 

CALL PRINT(.'BYTES READ $'); CALL PRINTADDR(NB); 

CALL PRINT(.'RECORDS WRITTEN $'); CALL PRINTHEX(P); 

CALL CRLF; 

END RELOC; 

/* ARRIVE HERE FROM THE SYSTEM MONITOR, READY TO READ THE" 


/* SET UP STACKPOINTER IN THE LOCAL AREA */ 

DECLARE STACK(16) ADDRESS, SP ADDRESS; 

SP = STACKPOINTER; STACKPOINTER = .STACK(LENGTH(STACK)); 

SBP = LENGTH(SBUFF); 

/* SET UP ThE SOURCE FILE */ 

CALL MOVE(FCBA,.SFCB,33); 

CALL MOVE(.('HEX' ,0) ,.SFCB(9) ,4) ; 

CALL SEARCH(.SFCB) ; 

IF (RFLAG := DCNT = 255) THEN 

CALL PRINT(. 'SOURCE IS READER?'); ELSE 
DO; CALL PRINT(.'SOURCE IS DISK?'); 










00337 3 

00338 3 

E$') ; 

00339 3 

00340 2 

00341 2 

00342 2 

00343 2 

00344 2 

00345 2 

00346 2 

00347 2 

00348 2 

); ELSE 
00349 2 

00350 3 

00351 3 

' ) ; 

00352 3 

00353 2 

00354 2 

00355 2 

00356 2 

00357 2 

00358 2 

00359 1 

00360 1 


CALL OPEN(.SFCB); 

IF DCNT = 255 THEN CALL PRINT 


'-CANNOT OPEN SOURC 


END; 

CALL CRLF; 


38 


CALL MOVE(.'COM' ,FCBA+9,3); 


/* REMOVE ANY EXISTING FILE BY THIS NAME */ 
CALL DELETE(FCBA); 


/* THEN OPEN A NEW FILE */ 

CALL MAKE (FCBA) ; FCB(32) = 0; /* 

IF DCNT = 255 THEN CALL PRINT(. 


CREATE AND SET NEXT RECORD */ _ 
'NO MORE DIRECTORY SPACES 


DO; CALL RELOC; 

CALL CLOSE(FCBA); 

IF DCNT = 255 THEN CALL PRINT 


'CANNOT CLOSE FILES 


END; 

CALL CRLF; 

/* RESTORE STACKPOINTER FOR RETURN */ 
STACKPOINTER = SP; 

RETURN 0; 

END LOADCOM; 

t 

EOF 
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